API Reference

POST /oid4vci/offers

Create a credential offer. Returns a URI that the holder's wallet scans to initiate the issuance flow.

Authentication: Secret API key

Request body

{
  "templateId": "550e8400-e29b-41d4-a716-446655440000",
  "claims": {
    "given_name": "Alice",
    "family_name": "Smith",
    "birth_date": "1990-01-15"
  }
}

Response 200

{
  "offer_id": "abc123",
  "credential_offer": {
    "credential_issuer": "https://api.verifiables.com",
    "credential_configuration_ids": ["eu.europa.ec.eudi.pid.1"],
    "grants": {
      "urn:ietf:params:oauth:grant-type:pre-authorized_code": {
        "pre-authorized_code": "oaKazRN8I0IbtZ0C7JuMn5",
        "tx_code": {
          "input_mode": "numeric",
          "length": 6,
          "description": "Enter the code"
        }
      }
    }
  },
  "credential_offer_uri": "openid-credential-offer://?credential_offer_uri=https%3A%2F%2F...",
  "tx_code": "847291"
}

POST /templates

Create or update a credential template. Upserts by type: if a template with the same type exists, it is updated.

Authentication: Secret API key

Request body

{
  "type": "eu.europa.ec.eudi.pid.1",
  "format": "mso_mdoc",
  "title": "EU Personal ID",
  "description": "European Union Person Identification Data",
  "claims": [
    { "name": "family_name", "type": "string", "mandatory": true },
    { "name": "given_name", "type": "string", "mandatory": true },
    { "name": "birth_date", "type": "string", "mandatory": true },
    { "name": "age_over_18", "type": "boolean" }
  ]
}

Response 200

Returns the created or updated template object.

GET /templates

List all credential templates.

Authentication: API key (publishable or secret)

Response 200

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "eu.europa.ec.eudi.pid.1",
    "format": "mso_mdoc",
    "title": "EU Personal ID",
    "description": "European Union Person Identification Data",
    "claims": [
      { "name": "family_name", "type": "string", "mandatory": true }
    ]
  }
]

GET /template/:id

Get a single template by ID.

Authentication: API key (publishable or secret)

Path parameters

Response 200

Returns the template object.

POST /type

Find templates by credential type.

Authentication: API key (publishable or secret)

Request body

{
  "type": "eu.europa.ec.eudi.pid.1"
}

Response 200

Returns an array of matching template objects.

Protocol endpoints

These endpoints are part of the OID4VCI protocol and are called by wallets. You do not call them directly; you only need POST /oid4vci/offers to create offers.

POST /oid4vci/par

Pushed Authorization Request. The wallet sends authorization parameters here instead of to the authorization endpoint directly.

Response 201

{
  "request_uri": "urn:ietf:params:oauth:request_uri:abc123",
  "expires_in": 60
}

GET /oid4vci/authorize

Authorization endpoint. The wallet navigates here with the PAR request URI.

Returns an authorization code as JSON { "code": "..." } or redirects to redirect_uri?code=...&state=....

POST /oid4vci/token

Token endpoint. Supports two grant types:

Pre-authorized code:

Authorization code (PKCE):

Both grant types accept optional client_assertion_type, client_assertion, and DPoP header.

Response 200

{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 3600
}

token_type is DPoP when the request carries a DPoP proof header, otherwise Bearer.

The token response does not contain a nonce (OID4VCI 1.0). Wallets fetch the proof nonce from POST /oid4vci/nonce before building the credential request.

POST /oid4vci/credential

Credential endpoint. The wallet requests the signed credential using the access token.

Response 200

{
  "credentials": [
    { "credential": "..." }
  ],
  "c_nonce": "new_nonce_456",
  "c_nonce_expires_in": 300
}

The primary response shape is the credentials array (one entry per proof); wallets should read credentials[0].credential. For backward compatibility with pre-1.0 wallets, a deprecated top-level credential field is also present when exactly one credential is issued (and it is the only field returned for legacy single-proof requests). New integrations must not rely on it.

Unlike the token response, the credential response still includes c_nonce and c_nonce_expires_in for the next proof.

Response 202 (deferred)

{
  "transaction_id": "txn_abc",
  "c_nonce": "nonce_789",
  "c_nonce_expires_in": 300
}

POST /oid4vci/deferred

Check status of a deferred credential.

Returns 200 with the credential when ready, or 202 with { "transaction_id", "interval": 5 } if still pending.

POST /oid4vci/nonce

Get a fresh nonce for credential requests. This is where wallets obtain the c_nonce to embed in their proof JWT (the token response no longer carries one).

Response 200

{
  "c_nonce": "fresh_nonce"
}

The response contains only c_nonce. There is no c_nonce_expires_in field; expiry is managed server-side.

Discovery endpoints

Schema objects

ClaimDefinition

{
  "name": "family_name",
  "type": "string",
  "mandatory": true,
  "sd": true
}