Skip to content

Verifier · Verify Credential

This page is for the Verifier role: the service that asks a holder to prove something. From your backend’s perspective, verification is two API calls — create an authorization request, then read the result. Everything between (fetching the signed request object, prompting the user, building the VP token, submitting it) happens on the wallet side.


Rendering diagram...

What you implement:

  1. Create the request. Post your DCQL query and verifier identity to Verifier Service.
  2. Deliver the request URI.
  3. Poll the result. Watch GET /v1/verifier/result/{session_id} until the session is completed.

You never construct or verify the VP token, the SD-JWT signature, or the key-binding JWT yourself. Verifier Service does all of that and exposes the outcome on the result endpoint as status (overall pass/fail) plus check_results[] (per-check breakdown).


Terminal window
curl -X POST https://verifier.turingspace.co/v1/verifier/authorization-request \
-H "X-API-Key: tcs_production_<your-api-key>" \
-H "Content-Type: application/json" \
-d '{
"dcql_query": {
"credentials": [
{
"id": "identity_credential",
"format": "dc+sd-jwt",
"meta": {
"vct_values": ["https://schema-registry.turingspace.co/schemas/TuringCerts_Standard_Credential/v2"]
},
"claims": [
{ "path": ["credentialName"] },
{ "path": ["issuedTime"] }
]
}
]
},
"verifier_private_key": "${VERIFIER_PRIVATE_KEY}",
"verifier_client_id": "did:iota:0xae72f18dc7b6af5b740edae8e4e0b2d3c9fb10a4e7d6c5b3a2f1e0d9c8b7a6f5",
"response_mode": "direct_post",
"expires_in": 300
}'

Response (201 Created):

{
"session_id": "b2c3d4e5-f6a7-8b9c-0d1e-2f3a4b5c6d7e",
"request_uri": "https://verifier.turingspace.co/v1/verifier/request/b2c3d4e5-f6a7-8b9c-0d1e-2f3a4b5c6d7e",
"authorization_request": "openid4vp://?client_id=did%3Aiota%3A0xae72...&request_uri=https%3A%2F%2Fverifier.turingspace.co%2Fv1%2Fverifier%2Frequest%2Fb2c3d4e5-...",
"expires_at": "2026-03-26T00:05:00Z"
}
NameTypeRequiredDescription
dcql_queryobjectYesWhich credentials and claims you need. See DCQL Query Structure.
verifier_private_keystringDID onlyBase64url-encoded raw Ed25519 (32 bytes). Used to sign the JAR (request object) so the wallet can verify who is asking. Required when verifier_client_id is a DID; omit it for x509_san_dns: and x509_hash: client IDs.
verifier_client_idstringYesThe verifier’s client ID, in one of three forms: a DID registered under your account (requires verifier_private_key); x509_san_dns:<dns-name>, where the DNS name must be a SAN of the server-configured leaf certificate; or x509_hash:<base64url SHA-256 of the leaf certificate DER>. Both x509_ forms sign the request object with the server-configured X.509 material and take no verifier_private_key. Wallets show this to the user during consent.
response_modestringNo"direct_post" (default — plain server-to-server VP delivery), "direct_post.jwt" (encrypted VP delivery using ECDH-ES; TCS auto-populates client_metadata.jwks with an ephemeral public key), or "fragment" (accepted, but TCS has no endpoint that receives a fragment response, so the session never completes — use "direct_post" or "direct_post.jwt").
expires_innumberNoSession TTL in seconds, from 60 to 3600 (default: 300).
client_metadataobjectNoclient_name, logo_uri, policy_uri, tos_uri — shown on the wallet’s consent screen. vp_formats_supported — the credential formats and algorithms you accept; when omitted, TCS sends dc+sd-jwt with ES256 and EdDSA. jwks — response-encryption keys; with direct_post.jwt, TCS replaces it with an ephemeral public key.
redirect_uristringNoWhere the wallet redirects the user after submission. Omit for headless flows.
request_uri_methodstringNo"get" (default) or "post". With "post", authorization_request carries request_uri_method=post and the wallet fetches the request object with HTTP POST.
StatusCause
400Malformed body (missing fields, empty dcql_query.credentials, expires_in outside 60–3600, etc.); a DID client ID without verifier_private_key, not registered under your account, or with a key that does not match it; an x509_ client ID that the server’s X.509 material does not cover
401Invalid or missing X-API-Key

How you put the request in front of the holder depends on the operating mode.

Pass authorization_request to Holder Service on behalf of the user. Holder Service fetches the signed request, prompts the user, builds the VP token, and submits it. See Holder · Manage Wallets & Credentials § 4.

Terminal window
curl -X POST https://holder.turingspace.co/v1/oid4vp/presentation \
-H "Authorization: Bearer ${HOLDER_USER_ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"authorization_request_uri": "openid4vp://?client_id=...&request_uri=...",
"selected_credentials": [
{ "credential_id": "...", "query_id": "identity_credential",
"disclosed_claims": ["credentialName", "issuedTime"] }
],
"holder_did": "did:iota:testnet:0x7a8b...",
"private_key": "${HOLDER_PRIVATE_KEY}"
}'

Response (200 OK):

{
"success": true,
"redirect_uri": "https://verifier.example.com/callback?session_id=b2c3d4e5-..."
}

redirect_uri is present only if the verifier configured one — deep-link the user there to complete the flow on the verifier side. From the verifier’s perspective, the session moves to completed and your verifier integration polls for the result in Step 3 below.

Render authorization_request as a QR code or open the deep link on the user’s device. Their wallet app handles the rest of OID4VP and posts the VP token directly to Verifier Service at POST /v1/verifier/presentation — see Non-Custodial Mode § Step 6 for that request.


Terminal window
curl https://verifier.turingspace.co/v1/verifier/result/b2c3d4e5-f6a7-8b9c-0d1e-2f3a4b5c6d7e \
-H "X-API-Key: tcs_production_<your-api-key>"

Response (200 OK) — completed:

{
"session_id": "b2c3d4e5-f6a7-8b9c-0d1e-2f3a4b5c6d7e",
"status": "completed",
"created_at": "2026-04-01T00:00:00.000Z",
"expires_at": "2026-04-01T00:05:00.000Z",
"verified_at": "2026-04-01T00:01:23.000Z",
"verification_mode": "fail_fast",
"check_results": [
{ "check": "credential_format", "status": "success", "reason_code": "credential_format_valid", "message": "The credential format is valid." },
{ "check": "signature", "status": "success", "reason_code": "signature_verified", "message": "The issuer signature was verified." },
{ "check": "key_binding", "status": "success", "reason_code": "key_binding_verified", "message": "The holder's proof of possession was verified." },
{ "check": "oid4vp_compliance", "status": "success", "reason_code": "oid4vp_request_valid", "message": "The verification request conforms to OID4VP." },
{ "check": "credential_status", "status": "skipped", "reason_code": "status_not_applicable", "message": "The credential carries no checkable revocation status reference." },
{ "check": "issuer_trust", "status": "skipped", "reason_code": "issuer_in_tr_approved", "message": "The issuer is in the trust registry and approved." },
{ "check": "issuer_governance", "status": "skipped", "reason_code": "partial_governance_coverage", "message": "The issuer is approved; governance coverage is partial." },
{ "check": "issuer_governance_vct_scope", "status": "skipped", "reason_code": "issuer_schema_scope_authorized", "message": "The issuer is registered to issue this credential type." },
{ "check": "schema_governance", "status": "skipped", "reason_code": "not_implemented", "message": "Trust layer check is not implemented yet." },
{ "check": "schema_version", "status": "skipped", "reason_code": "not_implemented", "message": "Trust layer check is not implemented yet." }
],
"presentation_metadata": {
"claims": {
"credentialName": "Bachelor of Science",
"issuedTime": "2026-01-15"
},
"credential_metadata": [
{
"issuer": "did:iota:testnet:0xabcdef...",
"credential_type": ["UniversityDegreeCredential"],
"issued_at": "2026-01-15T00:00:00.000Z",
"expires_at": "2027-01-15T00:00:00.000Z"
}
]
}
}

The session is completed only when no check in check_results returns status: "fail". Checks that report skipped do not block completion. To branch on overall outcome, check status === "completed" (boolean equivalent of “did the credential verify”). To explain why something failed to a user, walk check_results for the entries with status: "fail" and surface their message.

Response (200 OK) — failed (per-check breakdown):

{
"session_id": "b2c3d4e5-f6a7-8b9c-0d1e-2f3a4b5c6d7e",
"status": "failed",
"created_at": "2026-04-01T00:00:00.000Z",
"expires_at": "2026-04-01T00:05:00.000Z",
"verified_at": "2026-04-01T00:01:23.000Z",
"verification_mode": "fail_fast",
"check_results": [
{ "check": "credential_format", "status": "success", "reason_code": "credential_format_valid", "message": "The credential format is valid." },
{ "check": "signature", "status": "fail", "reason_code": "issuer_signature_invalid", "message": "The credential content does not match the issuer signature; authenticity could not be confirmed." },
{ "check": "key_binding", "status": "skipped", "reason_code": "prerequisite_failed", "message": "The signature check did not pass, so key binding was not evaluated." },
{ "check": "oid4vp_compliance", "status": "skipped", "reason_code": "skipped", "message": "A preceding check did not pass; this check was skipped." },
{ "check": "credential_status", "status": "skipped", "reason_code": "skipped", "message": "A preceding check did not pass; this check was skipped." },
{ "check": "issuer_trust", "status": "skipped", "reason_code": "skipped", "message": "A preceding check did not pass; this check was skipped." },
{ "check": "issuer_governance", "status": "skipped", "reason_code": "skipped", "message": "A preceding check did not pass; this check was skipped." },
{ "check": "schema_governance", "status": "skipped", "reason_code": "skipped", "message": "A preceding check did not pass; this check was skipped." },
{ "check": "schema_version", "status": "skipped", "reason_code": "skipped", "message": "A preceding check did not pass; this check was skipped." }
]
}

In fail_fast mode, no check runs after the first failure: each remaining check still appears in check_results, as status: "skipped" with reason_code: "skipped". In run_all mode every applicable check runs even after the first failure — useful when you need a full diagnostic for support tickets.

Where the mode is set. verification_mode is not a parameter on POST /v1/verifier/authorization-request. The wallet sends it when it submits the VP to POST /v1/verifier/presentation: "run_all" or "fail_fast" (default "fail_fast"). Non-Custodial Mode § Step 6 describes that request. The custodial Holder Service does not send verification_mode, so custodial sessions always use fail_fast. Verifier-side code only reads the mode back; it does not select the mode at request creation.

The closed set of check names and reason_code values currently surfaced by the verification pipeline. Use this to triage failures or to map error codes to user-facing copy.

checkreason_code (success)reason_code (fail)What it means
oid4vp_complianceoid4vp_request_validoid4vp_non_compliant, presentation_invalid, dcql_not_satisfiedOID4VP request + response shape conform to the spec. dcql_not_satisfied means the presented credentials do not satisfy the dcql_query
credential_formatcredential_format_validcredential_format_invalidThe presented payload is parseable as dc+sd-jwt
signaturesignature_verifiedissuer_signature_invalid, issuer_chain_untrusted, issuer_chain_expired, issuer_san_mismatch, issuer_key_not_resolvable, credential_expired, signature_verification_failedThe issuer signature verifies against the resolved issuer key. Covers issuer authenticity only — the holder’s proof of possession is reported separately as key_binding. For an issuer signing with an x5c certificate chain, the three chain-specific codes name what to fix: issuer_chain_untrusted is trust anchor configuration, issuer_chain_expired is certificate rotation, and issuer_san_mismatch means the credential’s iss could not be bound to the leaf certificate’s dNSName SANs — its host is not among them, it carries no host, or the SAN list is unusable for the binding (a wildcard, or a non-dNSName entry). issuer_key_not_resolvable is the narrower “no key came out of it” case — a DID that will not resolve, or a chain that cannot be read as a chain
key_bindingkey_binding_verifiedkb_jwt_missing, kb_jwt_malformed, kb_jwt_typ_invalid, kb_jwt_signature_invalid, kb_jwt_nonce_mismatch, kb_jwt_aud_mismatch, kb_jwt_iat_missing, kb_jwt_iat_in_future, kb_jwt_iat_too_old, kb_jwt_sd_hash_mismatch, holder_key_not_resolvableThe holder’s Key Binding JWT proves possession of the credential’s confirmation key, and binds this presentation to this request’s nonce, this verifier’s client_id, and the disclosures actually presented. Reported alongside signature by the same check. Also reports skipped with prerequisite_failed whenever the signature check did not pass, in which case key binding was never evaluated — never read that as a pass
credential_statuscredential_not_revokedcredential_revoked, credential_suspended, credential_status_unknown, status_list_unreachable, status_list_invalidThe credential’s Token Status List entry does not mark it revoked or suspended. Also reports skipped with status_check_disabled (enforcement off for this deployment), status_not_applicable (the credential carries no status reference), or prerequisite_failed (no credential reached this check)
issuer_trust——Whether the issuer DID belongs to a tenant in the Trust Registry. Always reports skipped, with issuer_in_tr_approved, issuer_in_tr_not_approved, issuer_not_in_tr, issuer_not_did (the issuer is a URL, not a DID), or prerequisite_failed (the issuer DID could not be determined)
issuer_governance——Whether the issuer’s tenant is approved. Always reports skipped, with partial_governance_coverage (approved) or prerequisite_failed (issuer_trust did not find an approved issuer)
issuer_governance_vct_scope——Whether the issuer registered the presented credential type (vct). Always reports skipped, with issuer_schema_scope_authorized or issuer_schema_scope_not_registered. Present only when issuer_governance reports partial_governance_coverage and the credential has a vct
schema_governance——Always reports skipped with not_implemented
schema_version——Always reports skipped with not_implemented
(any check)——status: "skipped" with reason_code: "skipped": in fail_fast mode, the check did not run because an earlier check failed

The issuer_trust, issuer_governance, issuer_governance_vct_scope, schema_governance and schema_version rows record observations only: they never report success or fail, so they never change the session status. Read their reason_code for what was observed — a skipped row does not mean the underlying property has been verified.

A credential issued on the X.509 / x5c path carries a status.status_list reference — a list URI plus an index — per draft-ietf-oauth-status-list-21. When status enforcement is on for the deployment, the Verifier Service fetches that list on every verification and reads the entry:

EntryResult
Validcredential_status reports success / credential_not_revoked
Revoked400 invalid_vp_token, credential_revoked
Suspended400 invalid_vp_token, credential_suspended
Reserved (0x03)400 invalid_vp_token, credential_status_unknown — no registered meaning, so it is not treated as valid

A credential with no status reference — including every did:iota-issued credential — reports skipped / status_not_applicable and verifies exactly as it did before. skipped never means the credential passed a status check; it means no check applied.

The check fails closed. If the list cannot be fetched or does not validate, verification is rejected (status_list_unreachable, status_list_invalid) rather than waved through — an unreachable list must never read as “not revoked”. A brief Status Issuer outage is cushioned by the last token successfully retrieved, but only within that token’s advertised ttl.

TCS does not follow redirects when it fetches a Status List. A 3xx answer (for example from http to https) counts as status_list_invalid, so a Status Issuer must publish the list at the exact URI in the credential.

Response (200 OK) — expired:

{
"session_id": "b2c3d4e5-f6a7-8b9c-0d1e-2f3a4b5c6d7e",
"status": "expired",
"created_at": "2026-04-01T00:00:00.000Z",
"expires_at": "2026-04-01T00:05:00.000Z",
"error": {
"code": "session_expired",
"message": "Session has expired"
}
}
StatusMeaning
pendingRequest created, waiting for the wallet to fetch the request object
in_progressWallet has fetched the request object, user has not yet submitted
completedVP token validated; presentation_metadata populated and no entry in check_results is fail (skipped entries are allowed)
failedAt least one entry in check_results is fail (e.g. bad signature, wrong nonce, expired credential), or the submission was rejected before the checks ran — then check_results is empty
expiredSession TTL elapsed without a wallet response; error populated

A practical poll loop runs every 2 seconds until status is terminal:

Terminal window
while true; do
RESULT=$(curl -s "$URL/v1/verifier/result/$SESSION_ID" -H "X-API-Key: $KEY")
STATUS=$(echo "$RESULT" | jq -r '.status')
case "$STATUS" in completed|failed|expired) echo "$RESULT" | jq .; break;; esac
sleep 2
done

A push-based webhook delivery mechanism (so verifier backends can avoid polling) is on the roadmap; until it ships, polling the result endpoint is the supported integration path. Contact us if push delivery is a hard requirement for your deployment.

StatusCause
401Invalid or missing X-API-Key
404Session not found — no session with this ID, or the session was created with another account’s API key

Two read-only endpoints on Verifier Service show the verification sessions of your tenant — for example, to build an audit view. Both take X-API-Key and only return sessions of the tenant the key belongs to. In these responses, status is upper case (PENDING, IN_PROGRESS, COMPLETED, FAILED, EXPIRED).

Terminal window
curl "https://verifier.turingspace.co/v1/verifications?status=COMPLETED&status=FAILED&limit=20" \
-H "X-API-Key: tcs_production_<your-api-key>"
Query parameterTypeDescription
statusstring, repeatableReturn only sessions with these statuses.
verified_afterISO 8601 dateReturn only sessions with verified_at on or after this time.
verified_beforeISO 8601 dateReturn only sessions with verified_at before this time. Must be later than verified_after, and the range between the two cannot be longer than 90 days.
qstringCase-insensitive match on part of session_id.
offsetintegerRecords to skip (default 0).
limitintegerRecords to return, 1 to 100 (default 20).

Sessions without a verified_at do not match verified_after or verified_before.

Response (200 OK) — sorted by created_at, newest first:

{
"items": [
{
"session_id": "b2c3d4e5-f6a7-8b9c-0d1e-2f3a4b5c6d7e",
"status": "COMPLETED",
"created_at": "2026-04-01T00:00:00.000Z",
"verified_at": "2026-04-01T00:01:23.000Z",
"expires_at": "2026-04-01T00:05:00.000Z",
"dcql_query_id": "identity_credential",
"verifier_client_id": "did:iota:0xae72f18dc7b6af5b740edae8e4e0b2d3c9fb10a4e7d6c5b3a2f1e0d9c8b7a6f5"
}
],
"total": 1,
"offset": 0,
"limit": 20
}

dcql_query_id is the id of the first entry in dcql_query.credentials.

Returns one session in full. Fields:

FieldDescription
session_id, status, created_at, verified_at, expires_atAs in the list. completed_at repeats verified_at.
client_idThe verifier_client_id of the request.
nonce, stateThe values sent to the wallet in the request object.
dcql_query_id, dcql_queryThe query of the request.
holder_didThe holder DID of the accepted presentation. null unless the session is COMPLETED.
disclosed_credentialsOne entry per submitted credential: query_id, vct, issuer_did, holder_did, issued_at, expires_at, disclosures ({ "name", "value" }, or { "raw", "parse_error": true } for a segment that cannot be decoded) and jwt_claims. null unless the session is COMPLETED.
check_resultsThe same entries as on the result endpoint, or null.
errorThe message of the first check_results entry with status: "fail", or null.
vp_tokenThe accepted presentation as TCS stores it: a JSON string of an object that maps each DCQL credential id to an array with its SD-JWT ({"<id>": ["<sd-jwt>"]}). It is not the raw request body; for direct_post.jwt it is the decrypted content. null unless the session is COMPLETED.
StatusCause
400Invalid query parameter (unknown status, a date that is not ISO 8601, verified_before not later than verified_after, a range longer than 90 days, limit outside 1–100)
401Invalid or missing X-API-Key
404Session not found — no session with this ID for your tenant (detail endpoint only)

DCQL (Digital Credentials Query Language) describes which credentials and claims you ask for. Every authorization request requires a dcql_query.

{
"dcql_query": {
"credentials": [ /* one or more credential descriptors */ ],
"credential_sets": [ /* optional */ ]
}
}

credential_sets (optional) is sent to the wallet in the request object. Each entry has options (a non-empty array of arrays of credential ids; each inner array is one acceptable combination), required (default true) and purpose (a reason that wallets can show). The verifier still requires a match for every entry in credentials: credential_sets does not make a credential optional.

FieldTypeRequiredDescription
idstringYesIdentifier for this credential in the query — also referenced by Holder Service in selected_credentials[].query_id.
formatstringYesUse "dc+sd-jwt" for SD-JWT VC. "vc+sd-jwt" is also accepted.
metaobjectYesContainer for credential-format-specific constraints. Required even if you only set one inner field.
meta.vct_valuesstring[]NoAcceptable VCT URLs. Wallet matches against the credential’s vct claim.
meta.type_valuesstring[][]NoAcceptable credential type combinations. The credential’s type must contain every value of at least one inner array; otherwise dcql_not_satisfied.
claimsobject[]NoSpecific claims to request as { "path": [...] }. Omit to let the wallet decide.
multiplebooleanNoDefault false. When false, more than one credential submitted for this id fails with dcql_not_satisfied.
require_cryptographic_holder_bindingbooleanNoDefault true. Asks the wallet for a holder-binding proof.
trusted_authoritiesobject[]NoRestrict to specific issuers, e.g. [{ "type": "did", "values": ["did:iota:0x..."] }].

Each claim path is a JSON path from the credential root: ["credentialName"], ["degreeName"]. Anything not listed remains hidden via SD-JWT selective disclosure.

Example — university degree with trusted issuer pinning

Section titled “Example — university degree with trusted issuer pinning”
{
"dcql_query": {
"credentials": [
{
"id": "degree_credential",
"format": "dc+sd-jwt",
"meta": {
"vct_values": ["https://schema-registry.turingspace.co/schemas/UniversityDegreeCredential/v1"]
},
"claims": [
{ "path": ["credentialName"] },
{ "path": ["studentId"] },
{ "path": ["degreeName"] }
],
"trusted_authorities": [
{ "type": "did", "values": ["did:iota:0xabc123def456"] }
]
}
]
}
}

The holder sees a consent screen listing only these three claims; everything else stays hidden.


  • Treating verifier_private_key like config. It is a signing key — store it in a secret manager and reference it at request time, not in .env files committed alongside source.
  • Polling forever. Always honour the expires_at from Step 1. Once the session expires (status: expired), stop polling and surface the failure to the user.
  • Asking for too many claims. Wallets will show every claim path on the consent screen. Asking for ten optional fields trains users to consent without reading. Ask for the minimum.
  • Forgetting vct_values. Without it the wallet may match credentials of unrelated types.
  • Using a plain URL as verifier_client_id. Verifier Service accepts only a DID registered under your account or an x509_san_dns: / x509_hash: client ID. Any other value is treated as a DID and fails with 400.