DCID Server SDK - Python

A Python SDK for interacting with the DCID Server API. This SDK provides a simple, type-safe interface for authentication and identity operations.

Installation

pip install dcid-server-sdk

Or install from source:

cd python
pip install -e .

Quick Start

from dcid_server_sdk import DCIDServerSDK, InitiateOTPOptions, ConfirmOTPOptions

# Initialize the SDK
sdk = DCIDServerSDK(
    api_key="your-api-key-here",
    environment="prod"  # or 'dev'
)

# Register/Sign-in with OTP
result = sdk.auth.register_otp(InitiateOTPOptions(email="user@example.com"))

# Confirm OTP and get tokens
tokens = sdk.auth.confirm_otp(
    ConfirmOTPOptions(
        email="user@example.com",
        otp="123456"
    )
)

print(f"Access Token: {tokens.access_token}")
print(f"Refresh Token: {tokens.refresh_token}")

API Reference

Initialization

from dcid_server_sdk import DCIDServerSDK

sdk = DCIDServerSDK(
    api_key="your-api-key-here",  # Required: API key
    environment="prod",  # Optional: Environment (default: "prod")
    timeout=30000,  # Optional: Request timeout in ms (default: 30000)
    default_headers={},  # Optional: Default headers
    logger=None,  # Optional: Custom logger
    enable_request_logging=False  # Optional: Enable request logging
)

Authentication Methods

auth.register_otp(options)

Initiates OTP registration/sign-in process. Covers POST /auth/sign-in/initiate.

Parameters:

• email (str, optional): User's email address
• phone (str, optional): User's phone number (with country code)

Returns: InitiateOTPResponse

• otp (str, optional): OTP code (only in dev environment)

Example:

from dcid_server_sdk import InitiateOTPOptions

# With email
result = sdk.auth.register_otp(InitiateOTPOptions(email="user@example.com"))

# With phone
result = sdk.auth.register_otp(InitiateOTPOptions(phone="+1234567890"))

auth.confirm_otp(options)

Confirms OTP and completes registration/sign-in. Covers POST /auth/sign-in/confirm.

Parameters:

• email (str, optional): User's email address
• phone (str, optional): User's phone number
• otp (str): The OTP code received by the user

Returns: TokenResponse

• access_token (str): JWT access token
• refresh_token (str): JWT refresh token

Example:

from dcid_server_sdk import ConfirmOTPOptions

tokens = sdk.auth.confirm_otp(
    ConfirmOTPOptions(
        email="user@example.com",
        otp="123456"
    )
)

# Set tokens for authenticated requests (done automatically)
sdk.set_tokens(tokens)

auth.refresh_token(options)

Refreshes the access token using refresh token. Covers POST /auth/refresh-token.

Parameters:

• refresh_token (str): The refresh token

Returns: TokenResponse

Example:

from dcid_server_sdk import RefreshTokenOptions

new_tokens = sdk.auth.refresh_token(
    RefreshTokenOptions(refresh_token="your-refresh-token")
)

Identity Methods

Encryption

from dcid_server_sdk import GenerateEncryptionKeyOptions, GetEncryptedKeyOptions

# Generate encryption key (will auto-refresh token if expired)
result = sdk.identity.encryption.generate_key(
    GenerateEncryptionKeyOptions(
        did="did:iden3:dcid:main:...",
        owner_email="user@example.com"
    )
)

# Get encrypted key
result = sdk.identity.encryption.get_key(
    GetEncryptedKeyOptions(did="did:iden3:dcid:main:...")
)

Issuer

from dcid_server_sdk import IssueCredentialOptions, GetCredentialOfferOptions

# Issue a credential
result = sdk.identity.issuer.issue_credential(
    IssueCredentialOptions(
        did="did:iden3:dcid:main:...",
        credential_name="KYCAgeCredential",
        values={"birthday": 25, "documentType": 2},
        owner_email="user@example.com"
    )
)

# Get credential offer (for MTP credentials)
result = sdk.identity.issuer.get_credential_offer(
    GetCredentialOfferOptions(
        claim_id="abc123...",
        tx_id="0x1234567890abcdef..."
    )
)

IPFS

from dcid_server_sdk import (
    StoreCredentialOptions,
    RetrieveUserCredentialOptions,
    GetAllUserCredentialsOptions
)

# Store credential to IPFS
result = sdk.identity.ipfs.store_credential(
    StoreCredentialOptions(
        did="did:iden3:dcid:main:...",
        credential_type="KYCAgeCredential",
        credential="U2FsdGVkX1+vupppZksvRf...",
        encrypted=True
    )
)

# Retrieve user credential
result = sdk.identity.ipfs.retrieve_user_credential(
    RetrieveUserCredentialOptions(
        did="did:iden3:dcid:main:...",
        credential_type="KYCAgeCredential",
        include_cid_only=False
    )
)

# Get all user credentials
result = sdk.identity.ipfs.get_all_user_credentials(
    GetAllUserCredentialsOptions(
        did="did:iden3:dcid:main:...",
        include_credential_data=False
    )
)

Verification

from dcid_server_sdk import (
    VerifySignInOptions,
    GetLinkStoreOptions,
    VerifyCallbackOptions
)

# Initiate verification
result = sdk.identity.verification.verify_sign_in(
    VerifySignInOptions(credential_name="ProofOfAgeCredential")
)

# Get proof request
proof_request = sdk.identity.verification.get_link_store(
    GetLinkStoreOptions(id="3297636436")
)

# Submit and verify proof
result = sdk.identity.verification.verify_callback(
    VerifyCallbackOptions(
        session_id="3297636436",
        token="eyJhbGciOiJncm90aDE2..."
    )
)

Analytics Methods

from dcid_server_sdk.modules.analytics.types import StartSessionEvent, EndSessionEvent

# Start a session
result = sdk.analytics.start_session(
    StartSessionEvent(
        user_id="user123",
        page_location="https://example.com/page"
    )
)

# End a session
result = sdk.analytics.end_session(
    EndSessionEvent(
        session_id=result.session_id,
        user_id="user123"
    )
)

Test Server

The Python SDK includes a test server that exposes HTTP endpoints for all SDK methods.

Running the Test Server

# Install server dependencies
pip install -r requirements-server.txt

# Set environment variables
export DCID_API_KEY="your-api-key"
export DCID_ENVIRONMENT="dev"  # or "prod"
export PORT="8080"  # optional, defaults to 8080

# Run the server
python test_server/main.py

Or using uvicorn directly:

uvicorn test_server.main:app --host 0.0.0.0 --port 8080 --reload

Test Server Endpoints

The test server provides the following endpoints:

Health Check

• GET /health - Health check endpoint

Authentication

• POST /api/auth/register-otp - Register OTP
• POST /api/auth/confirm-otp - Confirm OTP
• POST /api/auth/admin-login - Admin login
• POST /api/auth/refresh-token - Refresh token

Identity - Encryption

• POST /api/identity/encryption/generate-key - Generate encryption key
• POST /api/identity/encryption/get-key - Get encrypted key

Identity - Issuer

• POST /api/identity/issuer/issue-credential - Issue credential
• GET /api/identity/issuer/get-credential-offer - Get credential offer

Identity - IPFS

• POST /api/identity/ipfs/store-credential - Store credential
• POST /api/identity/ipfs/retrieve-user-credential - Retrieve user credential
• POST /api/identity/ipfs/get-all-user-credentials - Get all user credentials

Identity - Verification

• POST /api/identity/verification/verify-sign-in - Verify sign-in
• GET /api/identity/verification/link-store - Get link store
• POST /api/identity/verification/link-store - Post link store
• POST /api/identity/verification/callback - Verify callback

Analytics

• POST /api/analytics/start-session - Start session
• POST /api/analytics/end-session - End session

Example Usage

# Register OTP
curl -X POST http://localhost:8080/api/auth/register-otp \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com"}'

# Confirm OTP
curl -X POST http://localhost:8080/api/auth/confirm-otp \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "otp": "123456"}'

# Start analytics session
curl -X POST http://localhost:8080/api/analytics/start-session \
  -H "Content-Type: application/json" \
  -d '{"userId": "user123", "pageLocation": "https://example.com"}'

Error Handling

The SDK uses custom exception classes for different error types:

• DCIDServerSDKError: Base error class
• NetworkError: Network connectivity issues
• AuthenticationError: API-KEY or JWT token issues
• ServerError: Backend or gateway errors

from dcid_server_sdk import DCIDServerSDKError, NetworkError, AuthenticationError, ServerError

try:
    result = sdk.auth.register_otp(InitiateOTPOptions(email="user@example.com"))
except AuthenticationError as e:
    print(f"Authentication error: {e}")
    print(f"Is API key error: {e.is_api_key_error}")
except NetworkError as e:
    print(f"Network error: {e}")
except ServerError as e:
    print(f"Server error: {e}")
except DCIDServerSDKError as e:
    print(f"SDK error: {e}")

Python Version Support

• Python 3.8+

License

ISC