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.
What you do vs. what TCS does
Section titled “What you do vs. what TCS does”What you implement:
- Create the request. Post your DCQL query and verifier identity to Verifier Service.
- Deliver the request URI.
- Custodial mode: call Holder Service
POST /v1/oid4vp/presentationon behalf of the user. - Non-custodial mode: render the deep link as a QR code for the user’s wallet app.
- Custodial mode: call Holder Service
- Poll the result. Watch
GET /v1/verifier/result/{session_id}until the session iscompleted.
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).
Step 1 · Create an authorisation request
Section titled “Step 1 · Create an authorisation request”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"}Parameters
Section titled “Parameters”| Name | Type | Required | Description |
|---|---|---|---|
dcql_query | object | Yes | Which credentials and claims you need. See DCQL Query Structure. |
verifier_private_key | string | DID only | Base64url-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_id | string | Yes | The 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_mode | string | No | "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_in | number | No | Session TTL in seconds, from 60 to 3600 (default: 300). |
client_metadata | object | No | client_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_uri | string | No | Where the wallet redirects the user after submission. Omit for headless flows. |
request_uri_method | string | No | "get" (default) or "post". With "post", authorization_request carries request_uri_method=post and the wallet fetches the request object with HTTP POST. |
Errors
Section titled “Errors”| Status | Cause |
|---|---|
| 400 | Malformed 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 |
| 401 | Invalid or missing X-API-Key |
Step 2 · Deliver the request URI
Section titled “Step 2 · Deliver the request URI”How you put the request in front of the holder depends on the operating mode.
Custodial mode
Section titled “Custodial 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.
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.
Non-custodial mode
Section titled “Non-custodial mode”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.
Step 3 · Poll the result
Section titled “Step 3 · Poll the result”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.
reason_code reference
Section titled “reason_code reference”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.
check | reason_code (success) | reason_code (fail) | What it means |
|---|---|---|---|
oid4vp_compliance | oid4vp_request_valid | oid4vp_non_compliant, presentation_invalid, dcql_not_satisfied | OID4VP request + response shape conform to the spec. dcql_not_satisfied means the presented credentials do not satisfy the dcql_query |
credential_format | credential_format_valid | credential_format_invalid | The presented payload is parseable as dc+sd-jwt |
signature | signature_verified | issuer_signature_invalid, issuer_chain_untrusted, issuer_chain_expired, issuer_san_mismatch, issuer_key_not_resolvable, credential_expired, signature_verification_failed | The 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_binding | key_binding_verified | kb_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_resolvable | The 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_status | credential_not_revoked | credential_revoked, credential_suspended, credential_status_unknown, status_list_unreachable, status_list_invalid | The 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.
Revocation status
Section titled “Revocation status”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:
| Entry | Result |
|---|---|
| Valid | credential_status reports success / credential_not_revoked |
| Revoked | 400 invalid_vp_token, credential_revoked |
| Suspended | 400 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" }}Status values
Section titled “Status values”| Status | Meaning |
|---|---|
pending | Request created, waiting for the wallet to fetch the request object |
in_progress | Wallet has fetched the request object, user has not yet submitted |
completed | VP token validated; presentation_metadata populated and no entry in check_results is fail (skipped entries are allowed) |
failed | At 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 |
expired | Session TTL elapsed without a wallet response; error populated |
A practical poll loop runs every 2 seconds until status is terminal:
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 2doneA 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.
Errors
Section titled “Errors”| Status | Cause |
|---|---|
| 401 | Invalid or missing X-API-Key |
| 404 | Session not found — no session with this ID, or the session was created with another account’s API key |
List and inspect verifications
Section titled “List and inspect verifications”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).
GET /v1/verifications
Section titled “GET /v1/verifications”curl "https://verifier.turingspace.co/v1/verifications?status=COMPLETED&status=FAILED&limit=20" \ -H "X-API-Key: tcs_production_<your-api-key>"| Query parameter | Type | Description |
|---|---|---|
status | string, repeatable | Return only sessions with these statuses. |
verified_after | ISO 8601 date | Return only sessions with verified_at on or after this time. |
verified_before | ISO 8601 date | Return 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. |
q | string | Case-insensitive match on part of session_id. |
offset | integer | Records to skip (default 0). |
limit | integer | Records 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.
GET /v1/verifications/{session_id}
Section titled “GET /v1/verifications/{session_id}”Returns one session in full. Fields:
| Field | Description |
|---|---|
session_id, status, created_at, verified_at, expires_at | As in the list. completed_at repeats verified_at. |
client_id | The verifier_client_id of the request. |
nonce, state | The values sent to the wallet in the request object. |
dcql_query_id, dcql_query | The query of the request. |
holder_did | The holder DID of the accepted presentation. null unless the session is COMPLETED. |
disclosed_credentials | One 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_results | The same entries as on the result endpoint, or null. |
error | The message of the first check_results entry with status: "fail", or null. |
vp_token | The 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. |
Errors
Section titled “Errors”| Status | Cause |
|---|---|
| 400 | Invalid 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) |
| 401 | Invalid or missing X-API-Key |
| 404 | Session not found — no session with this ID for your tenant (detail endpoint only) |
DCQL Query Structure
Section titled “DCQL Query Structure”DCQL (Digital Credentials Query Language) describes which credentials and claims you ask for. Every authorization request requires a dcql_query.
Top-level
Section titled “Top-level”{ "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.
Credential descriptor fields
Section titled “Credential descriptor fields”| Field | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Identifier for this credential in the query — also referenced by Holder Service in selected_credentials[].query_id. |
format | string | Yes | Use "dc+sd-jwt" for SD-JWT VC. "vc+sd-jwt" is also accepted. |
meta | object | Yes | Container for credential-format-specific constraints. Required even if you only set one inner field. |
meta.vct_values | string[] | No | Acceptable VCT URLs. Wallet matches against the credential’s vct claim. |
meta.type_values | string[][] | No | Acceptable credential type combinations. The credential’s type must contain every value of at least one inner array; otherwise dcql_not_satisfied. |
claims | object[] | No | Specific claims to request as { "path": [...] }. Omit to let the wallet decide. |
multiple | boolean | No | Default false. When false, more than one credential submitted for this id fails with dcql_not_satisfied. |
require_cryptographic_holder_binding | boolean | No | Default true. Asks the wallet for a holder-binding proof. |
trusted_authorities | object[] | No | Restrict 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.
Common pitfalls
Section titled “Common pitfalls”- Treating
verifier_private_keylike config. It is a signing key — store it in a secret manager and reference it at request time, not in.envfiles committed alongside source. - Polling forever. Always honour the
expires_atfrom 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 anx509_san_dns:/x509_hash:client ID. Any other value is treated as a DID and fails with400.
What’s next
Section titled “What’s next”- Holder · Manage Wallets & Credentials — how the request URI in Step 2 turns into a presentation in custodial mode.
- Issuer · Issue Credential — the other half of the lifecycle.
- Trust & Schema Governance — register your verifier and pick what credentials you accept.
- Authentication — API key, JWT, and DPoP details.