Cloud SDK - API Reference

Exchanges a license key and Profile ID for an access-token / refresh-token pair.

To generate a License Key and Profile ID, visit: Generate Cloud SDK Key.

Request body

Both fields are required and identify which license and reader profile to activate.

{
  "licenseKey": "CS-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "profileId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Example

curl -X POST https://credenceid.com/cloudsdk/playground/v1/setup \
  -H "Origin: https://app.example.com" \
  -H "Content-Type: application/json" \
  -d '{
    "licenseKey": "CS-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "profileId":  "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }'

Response 200 OK

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI…",
  "refreshToken": "rt_550e8400-e29b-41d4-a716-446655440000",
  "expiresIn": 900,
  "tokenType": "Bearer",
  "customerName": "Credence Demo",
  "profileName": "Default Profile"
}

Errors

Atomically consumes the presented refresh token to issue a new access token and a new (rotated) refresh token. The original refresh token is invalidated immediately upon success; any attempt to reuse it will result in a 401 Unauthorized error.

Origin Validation

The Origin header is optional for server-side callers. When sent, it must match the domain bound to the refresh token. Browser callers send it automatically. If sent and it does not match, the request returns a DOMAIN_MISMATCH error.

Token Rotation Behavior

Upon every successful refresh:

• Rotation: A new refreshToken is issued. You must replace your locally stored value with this new token.
• Sliding Expiration: The refresh token's expiration is reset to 7 days from the time of the call. This allows the session to remain active indefinitely, provided it is refreshed before the current token expires.
• Immediate Invalidation: The previously presented refresh token is invalidated immediately. Do not attempt to reuse or retry with the old value.

Request body

The refresh token returned by /v1/setup is the only required field.

{
  "refreshToken": "rt_550e8400-e29b-41d4-a716-446655440000"
}

Example

curl -X POST https://credenceid.com/cloudsdk/playground/v1/refresh \
  -H "Content-Type: application/json" \
  -d '{ "refreshToken": "rt_550e8400-e29b-41d4-a716-446655440000" }'

Response 200 OK

{
  "accessToken": "eyJhbGciOiJIUzI1NiIs…",
  "refreshToken": "rt_550e8400-e29b-41d4-a716-446655440000",
  "expiresIn": 900,
  "tokenType": "Bearer"
}

customerName and profileName are not returned on refresh.

Errors

Request: body is empty.

curl -X POST https://credenceid.com/cloudsdk/playground/v1/getDocRequest \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response 201 Created

{
  "sessionId": "550e8400-e29b-41d4-a716-446655440000",
  "dcRequest": {
    "deviceRequest": "omdkb2NUeXBlcy4u…",
    "encryptionInfo": "omVub25jZVgu…"
  }
}

Errors

Decodes and verifies the encrypted wallet response returned by navigator.credentials.get(), runs cryptographic checks (issuer signature, IACA trust chain, mdoc binding), and returns the extracted identity claims.

Request body

{
  "sessionId": "550e8400-e29b-41d4-a716-446655440000",
  "data": "<base64url CBOR from credential.data>"
}

Example

curl -X POST https://credenceid.com/cloudsdk/playground/v1/verifyDocRequest \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "550e8400-e29b-41d4-a716-446655440000",
    "data": "eyJhbGciOiJFQ0RILUVTK..."
  }'

Response 200 OK: verification result

{
  "res": true,
  "resDetails": "{\"family_name\":\"Smith\",\"given_name\":\"Jane\",\"birth_date\":\"1990-01-15\"}"
}

Response 200 OK: user cancelled in wallet

{
  "cancelled": true,
  "message":   "Verification was cancelled by the user."
}

Cancellation and verification failure are two different response shapes, both returned as HTTP 200. Check for the cancelled field first; otherwise read res / resDetails.

Errors

Always send the Origin header explicitly.

Request: body is empty.

curl -X POST https://credenceid.com/cloudsdk/playground/dcapi/openid4vp/v1/initiate \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response 200 OK

{
  "sessionId": "550e8400-e29b-41d4-a716-446655440000",
  "payload": {
    "response_type": "vp_token",
    "response_mode": "dc_api.jwt",
    "nonce": "550e8400-…",
    "dcql_query": { "credentials": [ { "id": "cred1", "format": "mso_mdoc", "meta": { "doctype_value": "org.iso.18013.5.1.mDL" }, "claims": [ ... ] } ] },
    "client_metadata": {
      "jwks": { "keys": [ { "kty": "EC", "crv": "P-256", "x": "…", "y": "…", "use": "enc", "kid": "…", "alg": "ECDH-ES" } ] },
      "vp_formats_supported": { "mso_mdoc": { "deviceauth_alg_values": [-7], "issuerauth_alg_values": [-7] } }
    }
  }
}

Top-level fields

payload fields (verifier integrators don't usually inspect these, pass the object through)

Errors

Errors raised by this controller

Generic JWT-filter errors:

Decrypts the wallet's JWE response (Flow B), performs cryptographic validation on the embedded mdoc (issuer signature, IACA trust chain, and mdoc binding), and returns the extracted identity claims.

Request body

{
  "sessionId": "550e8400-e29b-41d4-a716-446655440000",
  "data": "<encrypted token (JWE compact serialization) from credential.data>"
}

curl -X POST https://credenceid.com/cloudsdk/playground/dcapi/openid4vp/v1/validate \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "550e8400-e29b-41d4-a716-446655440000",
    "data": "eyJhbGciOiJFQ0RILUVTK..."
  }'

Response 200 OK

{
  "res": true,
  "resDetails": "{\"identity\":{...},\"authentication\":{...}}"
}

Response 200 OK: user cancelled in wallet

{
  "cancelled": true,
  "message":   "Verification was cancelled by the user."
}

Cancellation and result use different shapes. Check for cancelled first; otherwise read res / resDetails.

Errors

Errors raised by this controller

Generic JWT-filter errors:

Request body (optional, application/json)

curl -X POST https://credenceid.com/cloudsdk/playground/openid4vp/v1/mdoc/initiate \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response 200 OK

{
  "sessionId": "550e8400-e29b-41d4-a716-446655440000",
  "walletUri": "mdoc-openid4vp://?client_id=…&request_uri=https%3A%2F%2Fcredenceid.com%2Fcloudsdk/playground%2Fopenid4vp%2Fv1%2Fmdoc%2Frequest%2F550e8400-…",
  "requestUri": "https://credenceid.com/cloudsdk/playground/openid4vp/v1/mdoc/request/550e8400-…"
}

Errors

Errors raised by this controller

Generic JWT-filter errors:

Polls for the verification result of an Annex B mdoc session. Returns 202 Accepted (with a pending status) while the wallet is completing the flow, and 200 OK (including the verification result) once the wallet has successfully posted its response.

Poll every ~2 seconds between calls.

Request body

{ "sessionId": "550e8400-e29b-41d4-a716-446655440000" }

curl -X POST https://credenceid.com/cloudsdk/playground/openid4vp/v1/mdoc/result \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "sessionId": "550e8400-e29b-41d4-a716-446655440000" }'

Response 200 OK: verification succeeded

{
  "success":  true,
  "identity": "{\"family_name\":\"Smith\",\"given_name\":\"Jane\",\"birth_date\":\"1990-01-15\"}",
  "error":    null
}

Response 200 OK: verification failed (wallet responded but credential didn't pass checks)

{
  "success":  false,
  "identity": null,
  "error":    "User denied consent."
}

This is HTTP 200 even when success=false. Verification failure is not an HTTP error. Use HTTP status to know whether the result is ready; use the success field to know the verification outcome.

Response 202 Accepted: result not yet available, keep polling

{ "status": "pending" }

Errors

Errors raised by this controller

Generic JWT-filter errors:

When the wallet redirects the user back to the verifier device with a response_code query parameter, that code is the credential. No Bearer token is required: the code itself is the auth. Single-use.

How the redirect happens: When you pass returnUrl in POST /openid4vp/v1/mdoc/initiate, the backend returns {"redirect_uri": "<returnUrl>?response_code=<code>"} to Wallet after the user consents. Wallet then redirects the user's browser to that URL. Your frontend reads the response_code from the URL query string and calls this endpoint to retrieve the result.

Query parameters

Request body

None.

curl "https://credenceid.com/cloudsdk/playground/openid4vp/v1/mdoc/resume?response_code=opaque-value"

Response 200 OK: verification succeeded

{
  "success":  true,
  "identity": "{\"family_name\":\"Smith\",\"given_name\":\"Jane\",\"birth_date\":\"1990-01-15\"}",
  "error":    null
}

Response 200 OK: verification failed (wallet responded but credential didn't pass checks)

{
  "success":  false,
  "identity": null,
  "error":    "User denied consent."
}

Same response shape as POST /openid4vp/v1/mdoc/result.

Response 202 Accepted: code is valid but the wallet's response is still being processed

{
  "error": "Validation not yet complete"
}

Errors

Request body

Empty.

curl -X POST https://credenceid.com/cloudsdk/playground/w3c/openid4vp/v1/initiate \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response 200 OK

{
  "sessionId": "550e8400-e29b-41d4-a716-446655440000",
  "authorizationRequest": {
    "client_id": "did:web:credenceid.com:cloudsdk/playground",
    "client_id_scheme": "did",
    "response_type": "vp_token",
    "response_mode": "direct_post",
    "response_uri": "https://credenceid.com/cloudsdk/playground/w3c/openid4vp/v1/callback",
    "nonce": "…",
    "state": "…",
    "presentation_definition": { … }
  },
  "callbackUrl": "https://credenceid.com/cloudsdk/playground/w3c/openid4vp/v1/callback",
  "requestUri": "https://credenceid.com/cloudsdk/playground/w3c/openid4vp/v1/request/550e8400-…"
}

authorizationRequest payload (verifier integrators don't usually inspect, pass through to the wallet)

Build the deep link

openid4vp://authorize?client_id=<authorizationRequest.client_id>&request_uri=<requestUri>

Errors

Errors raised by this controller

Generic JWT-filter errors:

Polls for the verification result of a W3C OpenID4VP session. Returns 202 Accepted (with a not yet completed status) while the wallet flow is in progress, and 200 OK (containing the full verification result) once the wallet has posted its callback.

Poll every ~2 seconds between calls.

Request body

{ "sessionId": "550e8400-e29b-41d4-a716-446655440000" }

curl -X POST https://credenceid.com/cloudsdk/playground/w3c/openid4vp/v1/validate \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "sessionId": "550e8400-e29b-41d4-a716-446655440000" }'

Response 200 OK: verification succeeded

{
  "success":  true,
  "claims": {
    "given_name":  "Jane",
    "family_name": "Smith",
    "birth_date":  "1990-01-15"
  },
  "issuer":            "did:web:issuer.example.com",
  "issuanceDate":      "2024-01-15T10:30:00Z",
  "expirationDate":    "2029-01-15T10:30:00Z",
  "credentialType":    ["VerifiableCredential", "DriversLicenseCredential"],
  "verificationDetails": {
    "vpSignatureValid":      true,
    "vcSignatureValid":      true,
    "nonceMatches":          true,
    "audienceMatches":       true,
    "issuerTrusted":         true,
    "notExpired":            true,
    "credentialTypeMatches": true
  }
}

Response 200 OK: verification failed

{
  "success": false,
  "error":   "Issuer not in trusted list."
}

Response 200 fields

verificationDetails fields (only present when success=true)

Response 202 Accepted: result not yet available, keep polling

{
  "error": "Session is not yet completed. Status: PENDING"
}

Errors

Errors raised by this controller

Generic JWT-filter errors:

Polling pattern (illustrative, Python)

import time, requests

def wait_for_result(base, token, session_id, interval=2.0, timeout=180):
    deadline = time.time() + timeout
    headers = {"Authorization": f"Bearer {token}", "Content-Type": "application/json"}
    while time.time() < deadline:
        r = requests.post(
            f"{base}/w3c/openid4vp/v1/validate",
            json={"sessionId": session_id},
            headers=headers,
        )
        if r.status_code == 200:
            return r.json()                       # full result with claims/verificationDetails
        if r.status_code == 202:
            time.sleep(interval); continue        # still pending
        r.raise_for_status()                      # 4xx/5xx -> raise
    raise TimeoutError("Verification did not complete in time.")