Loading search index…

Enter to open the first resultEsc to close
Browse documentationCreate a verification session | API Reference
Docs/API Reference/Sessions
SESSIONS

Create a verification session

POST/v1/sessions

Creates a tenant-scoped verification session in the environment selected by the API key. Request only the credential and claims your relying-party configuration allows; keep the API key on your server.

Backend integrationYour backend and SDK use a tenant API key.Try it: Console sign-in · selected tenant · Test only · no API key.

Request body

START HERE

Minimal example · Age verification (SD-JWT)

Same payload as the Quickstart. Replace the example issuer and credential type with your approved configuration. If your tenant requires a purpose, include its intended_use_id or use an approved request in Try it.

Example JSON
JSON
{
  "credentials": [{
    "id": "age-over-18",
    "format": "vc+sd-jwt",
    "issuer_id": "https://issuer.example.gov",
    "vct_values": ["https://sandbox.example/credentials/age-over-18"],
    "trust_domain": "pid",
    "claims": ["is_over_18"],
    "claim_filters": {"is_over_18": {"type": "boolean", "const": true}}
  }]
}

Example 201 response

Illustrative Test response; wallet links are shortened examples. Session created does not mean identity verified.

JSON response
{
  "session_id": "sess_example_7f3a1b2c",
  "livemode": false,
  "expires_at": "2030-01-01T12:15:00.000Z",
  "qr_code_url": "openid4vp://?client_id=example&response_type=vp_token&response_mode=direct_post&response_uri=https%3A%2F%2Fgateway.example.com%2Fv1%2Foid4vp%2Fresponse%2Fsess_example_7f3a1b2c&nonce=example&state=example&dcql_query=...&client_metadata=...",
  "deep_links": {
    "openid4vp": "openid4vp://?client_id=example&response_type=vp_token&response_mode=direct_post&response_uri=https%3A%2F%2Fgateway.example.com%2Fv1%2Foid4vp%2Fresponse%2Fsess_example_7f3a1b2c&nonce=example&state=example&dcql_query=...&client_metadata=...",
    "eudi_wallet": "eudi-openid4vp://?client_id=example&response_type=vp_token&response_mode=direct_post&response_uri=https%3A%2F%2Fgateway.example.com%2Fv1%2Foid4vp%2Fresponse%2Fsess_example_7f3a1b2c&nonce=example&state=example&dcql_query=...&client_metadata=..."
  }
}

Request schema

Credentials and common options. Select Full schema for transaction, SCA and same-device settings.

credentials
credentialsarray<object>required
Nested fields
idstringoptional
formatstringrequired
Allowed valuesvc+sd-jwtdc+sd-jwtmso_mdoc
issuer_idstringrequired
namespacestringoptional

mDOC namespace. Required for mso_mdoc.

doc_typestringoptional

mDOC doctype, sent as DCQL meta.doctype_value. Required for mso_mdoc, for example org.iso.18013.5.1.mDL or eu.europa.ec.eudi.pid.1.

vct_valuesarray<string>optional

Accepted SD-JWT VC types, sent as DCQL meta.vct_values. Required for vc+sd-jwt and dc+sd-jwt, for example urn:eudi:pid:1.

trust_domainstringoptional
Allowed valuespidpub_eaapriv_eaamdoc
claimsarray<string>required
claim_setsarray<array>optional
requiredbooleanoptional

Whether this credential is required for session success. False makes this DCQL credential query optional.

multiplebooleanoptional

Allow a DCQL Credential Query to return more than one matching credential. When multiple are returned, claims and verification_details are arrays for this credential id.

trusted_authority_akiarray<string>optional

DCQL trusted_authorities query using X.509 Authority Key Identifiers encoded as base64url. The verifier requires a match in the authenticated credential chain.

trusted_authority_etsi_tlarray<string>optional

DCQL trusted_authorities query using ETSI Trusted List identifiers. The verifier matches authenticated, current active PAA or QTSP certificate entries locally.

algstringoptional
Allowed valuesES256ES384ES512
subject_claim_pathsarray<string>optional
claim_filtersobjectoptional
View JSON schema
{
  "type": "object",
  "required": [
    "format",
    "issuer_id",
    "claims"
  ],
  "properties": {
    "id": {
      "type": "string"
    },
    "format": {
      "type": "string",
      "enum": [
        "vc+sd-jwt",
        "dc+sd-jwt",
        "mso_mdoc"
      ]
    },
    "issuer_id": {
      "type": "string"
    },
    "namespace": {
      "type": "string",
      "description": "mDOC namespace. Required for mso_mdoc."
    },
    "doc_type": {
      "type": "string",
      "description": "mDOC doctype, sent as DCQL meta.doctype_value. Required for mso_mdoc, for example org.iso.18013.5.1.mDL or eu.europa.ec.eudi.pid.1."
    },
    "vct_values": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "string",
        "minLength": 1
      },
      "description": "Accepted SD-JWT VC types, sent as DCQL meta.vct_values. Required for vc+sd-jwt and dc+sd-jwt, for example urn:eudi:pid:1."
    },
    "trust_domain": {
      "type": "string",
      "enum": [
        "pid",
        "pub_eaa",
        "priv_eaa",
        "mdoc"
      ]
    },
    "claims": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "string",
        "pattern": "^[A-Za-z0-9_]+(?:\\.[A-Za-z0-9_]+)*$",
        "description": "Flat mDOC claim name or dotted SD-JWT claim path, using the claim identifier defined for the selected format."
      }
    },
    "claim_sets": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "array",
        "minItems": 1,
        "items": {
          "type": "string"
        },
        "description": "One accepted combination of claim paths. When present, the wallet must disclose one complete combination; every path in claims must appear in at least one option."
      }
    },
    "required": {
      "type": "boolean",
      "default": true,
      "description": "Whether this credential is required for session success. False makes this DCQL credential query optional."
    },
    "multiple": {
      "type": "boolean",
      "default": false,
      "description": "Allow a DCQL Credential Query to return more than one matching credential. When multiple are returned, claims and verification_details are arrays for this credential id."
    },
    "trusted_authority_aki": {
      "type": "array",
      "minItems": 1,
      "maxItems": 32,
      "items": {
        "type": "string",
        "pattern": "^[A-Za-z0-9_-]+$",
        "maxLength": 128
      },
      "description": "DCQL trusted_authorities query using X.509 Authority Key Identifiers encoded as base64url. The verifier requires a match in the authenticated credential chain."
    },
    "trusted_authority_etsi_tl": {
      "type": "array",
      "minItems": 1,
      "maxItems": 8,
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 2048,
        "pattern": "^[A-Za-z][A-Za-z0-9+.-]*:[^\\s]+$"
      },
      "description": "DCQL trusted_authorities query using ETSI Trusted List identifiers. The verifier matches authenticated, current active PAA or QTSP certificate entries locally."
    },
    "alg": {
      "type": "string",
      "enum": [
        "ES256",
        "ES384",
        "ES512"
      ]
    },
    "subject_claim_paths": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "claim_filters": {
      "type": "object",
      "additionalProperties": {
        "type": "object"
      }
    }
  },
  "additionalProperties": false,
  "oneOf": [
    {
      "properties": {
        "format": {
          "const": "mso_mdoc"
        }
      },
      "required": [
        "namespace",
        "doc_type"
      ],
      "not": {
        "required": [
          "vct_values"
        ]
      }
    },
    {
      "properties": {
        "format": {
          "enum": [
            "vc+sd-jwt",
            "dc+sd-jwt"
          ]
        }
      },
      "required": [
        "vct_values"
      ],
      "not": {
        "anyOf": [
          {
            "required": [
              "namespace"
            ]
          },
          {
            "required": [
              "doc_type"
            ]
          }
        ]
      }
    }
  ]
}
View JSON schema
{
  "type": "object",
  "required": [
    "credentials"
  ],
  "properties": {
    "credentials": {
      "type": "array",
      "minItems": 1,
      "maxItems": 10,
      "items": {
        "$ref": "#/components/schemas/CredentialRequest"
      }
    }
  }
}
Common options
intended_use_idstringoptional

Registered relying-party intended-use identifier. Required when the relying-party policy defines intended uses.

relying_party_instance_idstringoptional

Active RP instance whose WRPAC signs this session. Required when the tenant has multiple active instances.

View JSON schema
{
  "type": "object",
  "required": [
    "credentials"
  ],
  "properties": {
    "intended_use_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Registered relying-party intended-use identifier. Required when the relying-party policy defines intended uses."
    },
    "relying_party_instance_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "description": "Active RP instance whose WRPAC signs this session. Required when the tenant has multiple active instances."
    }
  }
}

Responses

Response 201

Session created

application/json · Response schema
session_idstringrequired
relying_party_instance_idstringoptional

Selected RP instance whose WRPAC signs this session, when configured.

livemodebooleanrequired

Whether this session targets live data. False means sandbox/test data.

expires_atstring · date-timerequired
qr_code_urlstringrequired
client_idstringoptional

OpenID4VP client_id of the signed request. Present for the jar profile.

request_uristring · urioptional

URL the wallet fetches the signed Request Object from. Present for the jar profile.

request_uri_methodstringoptional

HTTP method the wallet uses for request_uri. Present for the jar profile.

Allowed valuesgetpost
deep_linksobjectrequired

Wallet invocation links: openid4vp, eudi_wallet (eudi-openid4vp://), mdoc_openid4vp, haip (haip-vp://) and universal_link, an HTTPS open-URL redirector (not an iOS Universal Link or Android App Link).

View JSON schema
{
  "type": "object",
  "required": [
    "session_id",
    "livemode",
    "expires_at",
    "qr_code_url",
    "deep_links"
  ],
  "properties": {
    "session_id": {
      "type": "string"
    },
    "relying_party_instance_id": {
      "type": "string",
      "description": "Selected RP instance whose WRPAC signs this session, when configured."
    },
    "livemode": {
      "type": "boolean",
      "description": "Whether this session targets live data. False means sandbox/test data."
    },
    "expires_at": {
      "type": "string",
      "format": "date-time"
    },
    "qr_code_url": {
      "type": "string"
    },
    "client_id": {
      "type": "string",
      "description": "OpenID4VP client_id of the signed request. Present for the jar profile."
    },
    "request_uri": {
      "type": "string",
      "format": "uri",
      "description": "URL the wallet fetches the signed Request Object from. Present for the jar profile."
    },
    "request_uri_method": {
      "type": "string",
      "enum": [
        "get",
        "post"
      ],
      "description": "HTTP method the wallet uses for request_uri. Present for the jar profile."
    },
    "deep_links": {
      "type": "object",
      "description": "Wallet invocation links: openid4vp, eudi_wallet (eudi-openid4vp://), mdoc_openid4vp, haip (haip-vp://) and universal_link, an HTTPS open-URL redirector (not an iOS Universal Link or Android App Link).",
      "additionalProperties": {
        "type": "string"
      }
    }
  }
}
Response 400

Invalid session request

application/json · Response schema
errorstringrequired
messagestringrequired
View JSON schema
{
  "type": "object",
  "required": [
    "error",
    "message"
  ],
  "properties": {
    "error": {
      "type": "string"
    },
    "message": {
      "type": "string"
    }
  }
}
Response 401

Missing or invalid API key

application/json · Response schema
errorstringrequired
messagestringrequired
View JSON schema
{
  "type": "object",
  "required": [
    "error",
    "message"
  ],
  "properties": {
    "error": {
      "type": "string"
    },
    "message": {
      "type": "string"
    }
  }
}
Response 403

Insufficient scope

application/json · Response schema
errorstringrequired
messagestringrequired
View JSON schema
{
  "type": "object",
  "required": [
    "error",
    "message"
  ],
  "properties": {
    "error": {
      "type": "string"
    },
    "message": {
      "type": "string"
    }
  }
}
Response 409

A tenant with multiple active RP instances must select one

application/json · Response schema
errorstringrequired
messagestringrequired
View JSON schema
{
  "type": "object",
  "required": [
    "error",
    "message"
  ],
  "properties": {
    "error": {
      "type": "string"
    },
    "message": {
      "type": "string"
    }
  }
}
Response 429

Rate limit exceeded

application/json · Response schema
errorstringrequired
messagestringrequired
View JSON schema
{
  "type": "object",
  "required": [
    "error",
    "message"
  ],
  "properties": {
    "error": {
      "type": "string"
    },
    "message": {
      "type": "string"
    }
  }
}

Examples

Runnable cURL and Node.js examples use the same request from the Quickstart.

cURL
curl --fail-with-body "$DLBR_GATEWAY_URL/v1/sessions" \
  -H "Authorization: Bearer $DLBR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "credentials": [{
      "id": "age-over-18",
      "format": "vc+sd-jwt",
      "issuer_id": "https://issuer.example.gov",
      "vct_values": ["https://sandbox.example/credentials/age-over-18"],
      "trust_domain": "pid",
      "claims": ["is_over_18"],
      "claim_filters": {"is_over_18": {"type": "boolean", "const": true}}
    }]
  }'

Ready to try it?

Edit this example or load an approved workspace profile.

← All public operations
© DLBR · API documentationv0.1.0 · a1293c1