Owl ID

    HTTP API

    Most integrations should use @owlid/sdk — it wraps these endpoints with typed clients, challenge handling, and the WebSocket presentation flow. Reach for the raw HTTP API only for non-TypeScript backends.

    Base URLs

    ServiceBase URLOpenAPI explorer
    Verificationhttps://api.owlid.apphttps://api.owlid.app/swagger-ui/
    Issuerhttps://issuer.owlid.apphttps://issuer.owlid.app/swagger-ui/

    The Swagger UI is the canonical, always-current reference — every route, request body, and response schema is generated from the live service. The tables below are a map of the surface.

    All endpoints require an Authorization: Bearer <api-key> header unless marked otherwise.

    Verification service

    MethodPathAuthDescription
    GET/healthnoneHealth check
    POST/openid4vp/responsenoneOpenID4VP direct_post endpoint
    POST/verify/dcqlkeyVerify a DCQL vp_token (OpenID4VP)
    GET/verify/challengekeyMint a single-use challenge nonce
    GET/trusted-issuerskeyList trusted issuer entries
    GET/predicateskeyList provable predicates
    GET/circuit-datakeyList set-membership circuit datasets
    POST/revocations/checkkeyCheck if a credential is revoked
    GET/revocations/listkeyList revoked credentials
    POST/presentation/sessionskeyOpen a QR/WS presentation session
    POST/trusted-issuersadminRegister a trusted issuer
    POST/revocations/revokeadminRevoke a credential
    POST/revocations/suspendadminSuspend a credential
    POST/revocations/reactivateadminReactivate a credential
    DELETE/admin/gdpr-erasure/{owner_public_key}gdprGDPR data erasure

    Issuer service

    MethodPathDescription
    GET/.well-known/did.jsondid:web document (CORS-public)
    GET/.well-known/openid-credential-issuerOpenID4VCI metadata
    GET/issuer-infoIssuer public key + display name
    GET/providersList identity verification providers
    POST/sessionsStart a verification session
    GET/sessions/{id}Read session state
    POST/sessions/{id}/submitSubmit identity data (form providers)
    GET/sessions/{id}/claimsRead verified claims for a session
    POST/sessions/{id}/issueIssue SD-JWT VC(s) from verified claims
    POST/sessions/{id}/completeComplete async (webhook) verification
    GET/polling/{session_id}Poll an async session until it terminates
    POST/tokenOpenID4VCI pre-authorized token
    POST/credentialOpenID4VCI single / Batch issuance
    GET/status/{id}IETF Token Status List (statuslist+jwt)

    Example — verify a presentation

    The verify endpoint takes a DCQL vp_token (OpenID4VP 1.0). The SDK's OwlVerifier.verify() wraps this for you.

    curl -X POST https://api.owlid.app/verify/dcql \
  -H "Authorization: Bearer $OWLID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vpToken": { "cred0": "<sd-jwt-vc>~<disclosure>~<disclosure>~<kb-jwt>" },
    "challenge": "the-nonce-used-in-kb-jwt",
    "query": { "credentials": [{ "id": "cred0", "format": "dc+sd-jwt", "claims": [] }] }
  }'

    Example — register a trusted issuer

    KEY=$(curl -s https://issuer.owlid.app/issuer-info | jq -r '.publicKey')

curl -X POST https://api.owlid.app/trusted-issuers \
  -H "Authorization: Bearer $OWLID_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"publicKey\": \"$KEY\", \"name\": \"Owl ID Issuer\"}"