Download OpenAPI specification:
Account/organization management, API key issuance, and multi-format credential issuance/verification for the VC Platform rebuild (see /requirements/PRD.md §5.1-§5.8). Covers everything implemented through Phase 2: org/membership CRUD, API keys, credential templates, four credential formats (VC-JWT, W3C VC 2.0 as JWT, W3C VC 1.1 with JSON-LD Data Integrity proofs, SD-JWT VC) over both the direct REST API and OpenID4VCI/VP 1.0 Final, Bitstring Status List revocation, the queryable audit trail, usage metering, and outbound webhooks (PRD §5.7/§5.9).
Console endpoints authenticate with an OIDC access token; the machine endpoints (Credentials, offers, presentations) authenticate with an org-scoped API key. Each operation states which it expects.
Creates the org and adds the caller as its first admin member, in one transaction. No RLS exemption needed: the org id is generated app-side and the tenant context is set to it before the insert.
| name required | string [ 1 .. 200 ] characters |
| slug required | string^[a-z0-9][a-z0-9-]{1,62}$ Lowercase alphanumeric with hyphens, 2-63 chars, starting alphanumeric. |
{- "name": "string",
- "slug": "string"
}{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "slug": "string",
- "createdAt": "2019-08-24T14:15:22Z",
- "updatedAt": "2019-08-24T14:15:22Z"
}Pre-tenant lookup via the list_user_memberships() database function — runs before any org context exists.
[- {
- "orgId": "25b2c2d5-a7fc-47d0-89e4-8709a1560bfa",
- "orgName": "string",
- "orgSlug": "string",
- "role": "admin"
}
]Admin-only. The slug is immutable — it appears in issuer identifiers that already-issued credentials point at.
| orgId required | string <uuid> |
| name required | string [ 1 .. 200 ] characters |
{- "name": "string"
}{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "slug": "string",
- "createdAt": "2019-08-24T14:15:22Z",
- "updatedAt": "2019-08-24T14:15:22Z"
}Admin-only. Invitations that have not yet been accepted — an invited address becomes a member on its first login.
| orgId required | string <uuid> |
[- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "email": "user@example.com",
- "role": "admin",
- "invitedBy": "9803bd85-1570-4d91-99f5-3a4d18ccfff0",
- "createdAt": "2019-08-24T14:15:22Z"
}
]Admin-only. Has no effect on an invitation that has already been accepted — that is a membership, removed via the members endpoint.
| orgId required | string <uuid> |
| invitationId required | string <uuid> |
{- "statusCode": 0,
- "error": "string",
- "message": "string"
}Admin-only. Re-sends the invite notification email without changing the invitation itself — use when the original delivery was missed or the recipient asks again.
| orgId required | string <uuid> |
| invitationId required | string <uuid> |
{- "statusCode": 0,
- "error": "string",
- "message": "string"
}Any member may list. A non-member gets the same 403 as a nonexistent org id — the membership check doubles as the tenant-existence check.
| orgId required | string <uuid> |
[- {
- "userId": "2c4a230c-5085-4924-a3e1-25fb4fc5965b",
- "email": "user@example.com",
- "displayName": "string",
- "role": "admin",
- "since": "2019-08-24T14:15:22Z"
}
]Admin-only. If the address belongs to an existing user of the identity
provider this deployment uses now, they become a member immediately
(status: active). Otherwise a pending invitation is recorded
(status: invited, userId: null) and resolved into a membership when
that address next signs in. Accounts left by a previous identity
provider do not count. Emails are compared without regard to case. If
two current accounts share the address, the request is refused with
409 and nobody is added.
| orgId required | string <uuid> |
| email required | string <email> |
| role required | string (OrgRole) Enum: "admin" "developer" "auditor" "billing" Org roles per PRD §5.1. |
| displayName | string [ 1 .. 200 ] characters |
{- "email": "user@example.com",
- "role": "admin",
- "displayName": "string"
}{- "userId": "2c4a230c-5085-4924-a3e1-25fb4fc5965b",
- "email": "user@example.com",
- "role": "admin",
- "status": "active"
}Admin-only. Refuses to demote the last remaining admin.
| orgId required | string <uuid> |
| userId required | string <uuid> |
| role required | string (OrgRole) Enum: "admin" "developer" "auditor" "billing" Org roles per PRD §5.1. |
{- "role": "admin"
}{- "orgId": "25b2c2d5-a7fc-47d0-89e4-8709a1560bfa",
- "userId": "2c4a230c-5085-4924-a3e1-25fb4fc5965b",
- "role": "admin",
- "createdAt": "2019-08-24T14:15:22Z"
}Admin-only. The plaintext secret is returned exactly once in this response — only its SHA-256 hash is persisted. There is no way to retrieve it again after this call.
| orgId required | string <uuid> |
| name required | string [ 1 .. 200 ] characters |
| scopes required | Array of strings (ApiKeyScope) non-empty Items Enum: "issue" "verify" "admin" "agent-present" |
| agentIds | Array of strings <uuid> [ 1 .. 20 ] items unique [ items <uuid > ] Required with the |
| verifierOrgIds | Array of strings <uuid> [ 1 .. 20 ] items unique [ items <uuid > ] Required with the |
| expiresAt | string <date-time> ISO 8601 timestamp. Omit for a key that doesn't expire. |
{- "name": "string",
- "scopes": [
- "issue"
], - "agentIds": [
- "497f6eca-6276-4993-bfeb-53cbbbba6f08"
], - "verifierOrgIds": [
- "497f6eca-6276-4993-bfeb-53cbbbba6f08"
], - "expiresAt": "2019-08-24T14:15:22Z"
}{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "keyPrefix": "string",
- "scopes": [
- "issue"
], - "agentIds": [
- "497f6eca-6276-4993-bfeb-53cbbbba6f08"
], - "verifierOrgIds": [
- "497f6eca-6276-4993-bfeb-53cbbbba6f08"
], - "createdBy": "25a02396-1048-48f9-bf93-102d2fb7895e",
- "createdAt": "2019-08-24T14:15:22Z",
- "expiresAt": "2019-08-24T14:15:22Z",
- "lastUsedAt": "2019-08-24T14:15:22Z",
- "revokedAt": "2019-08-24T14:15:22Z",
- "secret": "string"
}Any member may list. Never includes the secret or its hash.
| orgId required | string <uuid> |
[- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "keyPrefix": "string",
- "scopes": [
- "issue"
], - "agentIds": [
- "497f6eca-6276-4993-bfeb-53cbbbba6f08"
], - "verifierOrgIds": [
- "497f6eca-6276-4993-bfeb-53cbbbba6f08"
], - "createdBy": "25a02396-1048-48f9-bf93-102d2fb7895e",
- "createdAt": "2019-08-24T14:15:22Z",
- "expiresAt": "2019-08-24T14:15:22Z",
- "lastUsedAt": "2019-08-24T14:15:22Z",
- "revokedAt": "2019-08-24T14:15:22Z"
}
]Admin-only. Idempotent — revoking an already-revoked key returns 204 without recording a second audit event.
| orgId required | string <uuid> |
| keyId required | string <uuid> |
{- "statusCode": 0,
- "error": "string",
- "message": "string"
}Credential template & schema management, console-managed (PRD §5.3).
A template's name and (optional) description are also served
publicly, at the host root (not under /api), as the SD-JWT VC Type
Metadata document for its dc+sd-jwt credentials
(draft-ietf-oauth-sd-jwt-vc-19 §5.3.1): a plain GET on the vct value
baked into every such credential, no .well-known indirection.
GET /vct/v1/{orgId}/{templateId} — { vct, name, description? };
404 if the template doesn't exist or doesn't offer dc+sd-jwt.GET /vct/v1/skills/{name}/{version} — the same document for a
skill type: one definition per deployment, identical for every
organisation, so every issuer of the skill emits the same vct
({PLATFORM_PUBLIC_URL}/vct/v1/skills/{name}/{version}; the host
differs between sandbox and production, so pin one per environment).
Each claim is sd: never and mandatory. 404 for an unknown skill or
version. A version never changes: credentials already issued commit
to its exact content through vct#integrity. Currently:
payment-order-create versions 1 and 2 (an agent may create payment
orders in the named application, within stated limits; not a mandate
to execute a payment). Version 2 adds payee_policy (listed or
any) and max_amount_per_day. account-transactions-read version 1
(an agent may read the bookings of listed accounts in the named
application; it cannot create anything). Create an organisation's template for it with
POST /orgs/{orgId}/templates/skill-types/{name}/{version}.Admin-only. claimsSchema is checked against subjectClaims at
issuance only for a template that sets enforceClaimsSchema: true;
for every other template it is stored and not checked. formats declares which wire
formats this template may be rendered in; all five CredentialFormat
values have a renderer. Revocation is narrower: bitstring-status-list
is implemented, token-status-list is declarable but rejected at
issuance, and mso_mdoc has no revocation mechanism at all yet —
declaring revocable: true for it is accepted at creation time but
rejected with 400 at issuance.
| orgId required | string <uuid> |
| name required | string [ 1 .. 200 ] characters |
| description | string [ 1 .. 2000 ] characters Shown alongside |
| mdocNamespace | string [ 1 .. 200 ] characters
|
| claimsSchema required | object A JSON Schema the subjectClaims are meant to satisfy. Accepted
and stored for every template; checked at issuance only when
|
| enforceClaimsSchema | boolean Default: false When true, every credential's |
| formats required | Array of strings (CredentialFormat) non-empty Items Enum: "vc+jwt" "vc11+ld" "vc20" "dc+sd-jwt" "mso_mdoc" |
| validityPeriodDays | integer >= 1 If set, an issued credential's validUntil is validFrom + this many days. Omit for a credential that doesn't expire. |
| revocable | boolean Default: false Whether credentials from this template can be revoked. Intent only — which status mechanism carries it is determined by the credential's format, not chosen here, because the format's own specification decides. When true, issuance allocates a status entry and the renderer embeds the pointer its format defines. |
{- "name": "string",
- "description": "string",
- "mdocNamespace": "string",
- "claimsSchema": { },
- "enforceClaimsSchema": false,
- "formats": [
- "vc+jwt"
], - "validityPeriodDays": 1,
- "revocable": false
}{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "orgId": "25b2c2d5-a7fc-47d0-89e4-8709a1560bfa",
- "name": "string",
- "description": "string",
- "mdocNamespace": "string",
- "claimsSchema": { },
- "enforceClaimsSchema": true,
- "formats": [
- "vc+jwt"
], - "validityPeriodDays": 0,
- "revocable": true,
- "createdAt": "2019-08-24T14:15:22Z",
- "updatedAt": "2019-08-24T14:15:22Z"
}Any member may list.
| orgId required | string <uuid> |
[- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "orgId": "25b2c2d5-a7fc-47d0-89e4-8709a1560bfa",
- "name": "string",
- "description": "string",
- "mdocNamespace": "string",
- "claimsSchema": { },
- "enforceClaimsSchema": true,
- "formats": [
- "vc+jwt"
], - "validityPeriodDays": 0,
- "revocable": true,
- "createdAt": "2019-08-24T14:15:22Z",
- "updatedAt": "2019-08-24T14:15:22Z"
}
]Admin-only. Creates the template for a registered skill type (see the
Templates tag for the document served for it), with every field taken
from the definition: the canonical vct, its claim metadata (all
sd: never), the claimsSchema with enforceClaimsSchema on,
dc+sd-jwt only, revocable, and vct#integrity on. Credentials
issued from it therefore carry the skill's canonical vct and an
integrity value equal to the hash of the document served for the skill.
Credentials of a skill type are issued only through an approved
grant (the Agent skills tag): an administrator, signed in to the
console, who re-authenticated for exactly those terms. POST /credentials, OpenID4VCI offers, the MCP tools and the end-user flow
all answer 403 for such a template, whatever the caller's key or role.
Idempotent: an organisation has one template per skill type
version, and a repeated call returns it unchanged with status 200,
whether or not this call created it. validityPeriodDays is only read
when the template is created; change it afterwards with PATCH.
The vct namespace {PLATFORM_PUBLIC_URL}/vct/v1/skills/ is
reserved: POST /orgs/{orgId}/templates refuses a vct under it. A
skill template can be changed only in validityPeriodDays and
keyAttestationRequired; a different definition is a new skill type
version.
| orgId required | string <uuid> |
| name required | string Example: payment-order-create |
| version required | integer >= 1 |
| validityPeriodDays | integer [ 1 .. 365 ] Validity of an issued skill credential, in days. Default:
the skill type's (1 day for |
{- "validityPeriodDays": 1
}{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "orgId": "25b2c2d5-a7fc-47d0-89e4-8709a1560bfa",
- "name": "string",
- "description": "string",
- "mdocNamespace": "string",
- "claimsSchema": { },
- "enforceClaimsSchema": true,
- "formats": [
- "vc+jwt"
], - "validityPeriodDays": 0,
- "revocable": true,
- "createdAt": "2019-08-24T14:15:22Z",
- "updatedAt": "2019-08-24T14:15:22Z"
}Any member may read. A nonexistent or foreign-org template id gets 404 — same no-leak pattern as everywhere else org-scoped.
| orgId required | string <uuid> |
| templateId required | string <uuid> |
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "orgId": "25b2c2d5-a7fc-47d0-89e4-8709a1560bfa",
- "name": "string",
- "description": "string",
- "mdocNamespace": "string",
- "claimsSchema": { },
- "enforceClaimsSchema": true,
- "formats": [
- "vc+jwt"
], - "validityPeriodDays": 0,
- "revocable": true,
- "createdAt": "2019-08-24T14:15:22Z",
- "updatedAt": "2019-08-24T14:15:22Z"
}Admin-only, partial update. Affects future issuance only — credentials already issued from this template are signed artifacts and do not change. PRD §5.3's "without code deploys" is what this exists for.
| orgId required | string <uuid> |
| templateId required | string <uuid> |
| name | string [ 1 .. 200 ] characters |
| description | string [ 1 .. 2000 ] characters |
| mdocNamespace | string [ 1 .. 200 ] characters See CreateTemplateRequest.mdocNamespace. |
| claimsSchema | object See CreateTemplateRequest.claimsSchema. Replacing it with a schema that is not valid JSON Schema is a 400 while |
| enforceClaimsSchema | boolean See CreateTemplateRequest.enforceClaimsSchema. |
| formats | Array of strings (CredentialFormat) non-empty Items Enum: "vc+jwt" "vc11+ld" "vc20" "dc+sd-jwt" "mso_mdoc" |
| validityPeriodDays | integer >= 1 |
| revocable | boolean |
{- "name": "string",
- "description": "string",
- "mdocNamespace": "string",
- "claimsSchema": { },
- "enforceClaimsSchema": true,
- "formats": [
- "vc+jwt"
], - "validityPeriodDays": 1,
- "revocable": true
}{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "orgId": "25b2c2d5-a7fc-47d0-89e4-8709a1560bfa",
- "name": "string",
- "description": "string",
- "mdocNamespace": "string",
- "claimsSchema": { },
- "enforceClaimsSchema": true,
- "formats": [
- "vc+jwt"
], - "validityPeriodDays": 0,
- "revocable": true,
- "createdAt": "2019-08-24T14:15:22Z",
- "updatedAt": "2019-08-24T14:15:22Z"
}Admin-only. Already-issued credentials survive — they are self-contained signed documents, and the audit trail keeps its record of them.
| orgId required | string <uuid> |
| templateId required | string <uuid> |
{- "statusCode": 0,
- "error": "string",
- "message": "string"
}Granting an agent a skill (see the skill types under Templates): authority a relying party acts on, within stated limits. Console session only, organisation administrator, never an API key or the agent itself, because a skill is granted by a person who has just authenticated again.
The flow, in three steps:
POST .../skills/approvals: name the agent and the terms. The platform fills in the agent,
the skill and its version, checks the grant against the skill type's schema, and records
exactly what would be signed, with a SHA-256 termsHash and a one-time nonce. Nothing is issued.max_age=0 (or prompt=login) and nonce=<that nonce>. The ID token that comes back carries
auth_time, amr and the nonce. (An OIDC provider reports these in the ID token, not the
access token: Zitadel documents auth_time, amr and acr as ID token claims only.)POST .../approve with that ID token, authenticated as the same administrator. The platform
verifies the token, checks that the nonce is this approval's, that auth_time is recent (default
300 seconds, SKILL_APPROVAL_MAX_AUTH_AGE_SECONDS) and later than the request for approval,
spends the approval once, and only then issues the credential, from the terms stored in step 1
and never from anything sent with the approval.A session that did not come from the identity provider (credential login, the local dev header)
has no ID token and cannot approve. The audit trail records the approver, when and how they
authenticated (amr) and the terms hash. Every other route to a skill credential is refused:
POST /credentials, OpenID4VCI offers, the MCP tools and the end-user flow answer 403.
Admin or auditor. Agents are created through the MCP endpoint with an API key; this lists them for the console.
| orgId required | string <uuid> |
[- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "revokedAt": "2019-08-24T14:15:22Z",
- "createdAt": "2019-08-24T14:15:22Z"
}
]Admin or auditor. Includes who approved each grant, when and how they authenticated, and the hash of the terms they were shown.
| orgId required | string <uuid> |
| agentId required | string <uuid> |
[- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "agentId": "bc309ecf-5f66-4057-93c5-6611cc9cb7b2",
- "credentialId": "f568fec0-10b6-4b94-9daf-e62c50c9bf3e",
- "skillType": "string",
- "termsHash": "string",
- "verifierOrgId": "eb536923-e647-4c69-a0ee-3bc3e555947a",
- "approvedByUserId": "74506145-90c2-42eb-9f45-57bc31c8817e",
- "approvedAt": "2019-08-24T14:15:22Z",
- "authTime": "2019-08-24T14:15:22Z",
- "amr": [
- "string"
], - "expiresAt": "2019-08-24T14:15:22Z",
- "revokedAt": "2019-08-24T14:15:22Z"
}
]Admin only, console session. Records exactly what would be signed and returns what the console
must show the administrator for approval, plus the nonce to send through the identity provider
(step 2). Issues nothing. The approval is valid for 10 minutes, can be approved once, and only
by the administrator who requested it.
The organisation's template for the skill type is created from the definition if it has none yet.
The credential's validity is that template's (1 day by default for payment-order-create); it
is part of the terms the administrator sees.
The agent must exist and not be revoked. A grant that breaks the skill type's schema is a 400 listing each violation, before anyone is asked to approve it.
| orgId required | string <uuid> |
| agentId required | string <uuid> |
| skillType required | string^[a-z0-9-]{1,100}/[1-9][0-9]{0,5}$
|
| application required | string [ 1 .. 200 ] characters The application the skill is valid in, and only there. |
| verifierOrgId required | string <uuid> The organisation on this platform the agent may present this skill to (typically the application's own organisation, the verifier). Part of what the administrator approves and of the terms hash: the agent can present the skill to no other organisation, so its limits are not shown to a verifier nobody named. |
| constraints required | object What the agent may not exceed; its shape is the skill type's own. IBANs in upper-case canonical form. Anything else is a 400.
|
{- "skillType": "payment-order-create/1",
- "application": "string",
- "verifierOrgId": "eb536923-e647-4c69-a0ee-3bc3e555947a",
- "constraints": {
- "currency": "EUR",
- "max_amount_per_order": 1000,
- "max_amount_per_day": 10000,
- "debtor_ibans": [
- "DE18430609671010041900"
], - "payee_policy": "any"
}
}{- "approvalId": "23bbe807-dea1-4601-b208-07fd1aaad2b6",
- "nonce": "string",
- "termsHash": "string",
- "terms": {
- "v": 2,
- "orgId": "25b2c2d5-a7fc-47d0-89e4-8709a1560bfa",
- "agentId": "bc309ecf-5f66-4057-93c5-6611cc9cb7b2",
- "verifierOrgId": "eb536923-e647-4c69-a0ee-3bc3e555947a",
- "agentKeyThumbprint": "string",
- "skillType": "string",
- "vct": "string",
- "validityDays": 0,
- "claims": { }
}, - "expiresAt": "2019-08-24T14:15:22Z",
- "maxAgeSeconds": 0
}Admin only, console session, the same administrator who started the approval. Authenticated with the access token as usual; the body carries the ID token from the re-authentication of step 2.
Refused with 403 unless the ID token is validly signed by the identity provider, belongs to the
signed-in user, carries this approval's nonce, reports an auth_time within the freshness window
and not before the approval was requested, and used multi-factor authentication (amr contains
mfa; always required: a password alone is a 403, and no setting turns it off). A refusal leaves the
approval unspent, so the administrator can authenticate again.
A valid approval is spent exactly once; a replay is a 404.
409 if, between the request and the approval, the agent was revoked, its key changed, or the skill template's validity changed: what the administrator was shown no longer holds.
| orgId required | string <uuid> |
| agentId required | string <uuid> |
| approvalId required | string <uuid> |
| idToken required | string The ID token returned by the identity provider when the administrator re-authenticated for this approval. |
{- "idToken": "string"
}{- "skillId": "97d3165d-e1dd-4955-972c-95ebf04dd091",
- "credentialId": "f568fec0-10b6-4b94-9daf-e62c50c9bf3e",
- "termsHash": "string",
- "expiresAt": "2019-08-24T14:15:22Z"
}Admin only, console session. Flips the credential's status-list entry, so a relying party that checks status sees it revoked, and marks the grant. No step-up: ending an authority must be easy and can only narrow. Idempotent.
| orgId required | string <uuid> |
| agentId required | string <uuid> |
| skillId required | string <uuid> |
{- "skillId": "97d3165d-e1dd-4955-972c-95ebf04dd091",
- "revoked": true,
- "revokedAt": "2019-08-24T14:15:22Z"
}API key with the admin or the agent-present scope. The same act as the MCP tool present_to_request, for a
backend that is not an MCP client: the verifier's own server passes the authorizationRequest it created, and
the platform signs the agent's identity and the skill it was granted for the audience and nonce of the request
the verifier stored, and submits them. The skill goes only to the organisation its approver named, and only
while the grant is active. Requests for the Digital Credentials API, with encrypted responses (jarm) or for the
same-device flow (redirectUri) are refused, as are requests of other platforms.
An agent-present key may present only for the agents in its agentIds and to the verifiers in its
verifierOrgIds; anything else is 403, and is audited as agent.present_refused. An admin key may present for
any agent of its organisation.
A refusal by the verifier is an outcome, not an error: it comes back as 200 with accepted: false and the
error codes per credential in outcome.
| agentId required | string <uuid> |
| request required | string [ 1 .. 8000 ] characters The verifier's |
{- "request": "string"
}{- "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
- "verifierOrgId": "eb536923-e647-4c69-a0ee-3bc3e555947a",
- "accepted": true,
- "presented": [
- {
- "queryId": "string",
- "kind": "identity",
- "credentialId": "f568fec0-10b6-4b94-9daf-e62c50c9bf3e"
}
], - "outcome": [
- {
- "queryId": "string",
- "verified": true,
- "errorCodes": [
- "string"
]
}
]
}API-key-authenticated (issue scope), not a console token — there is
deliberately no {orgId} in this path; the API key itself is the
tenant selector, the same way a Stripe key implies your account.
The org's Ed25519 signing key is provisioned lazily on first issuance (one key per org for Phase 0) and reused after. The platform constructs and encodes the JWS header/payload itself and sends only opaque signing-input bytes to the isolated signing service — it never sees credential content, and the platform never sees the private key (Architecture §5).
| templateId required | string <uuid> |
| subjectClaims required | object Checked against the template's claimsSchema only when the template sets |
| format | string Default: "vc+jwt" Enum: "vc+jwt" "vc11+ld" "vc20" "dc+sd-jwt" "mso_mdoc" Which of the template's declared formats to render. Defaults to
|
{- "templateId": "196100ac-4eec-4fb6-a7f7-86c8b584771d",
- "subjectClaims": { },
- "format": "vc+jwt"
}{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "format": "vc+jwt",
- "credential": "string",
- "issuedAt": "2019-08-24T14:15:22Z",
- "validFrom": "2019-08-24T14:15:22Z",
- "validUntil": "2019-08-24T14:15:22Z"
}API-key-authenticated (verify scope). Signature verification
never calls the signing service — the issuer identifier is a
did:jwk, which embeds the public key directly, so resolving it is
pure decoding, not a network round trip. Always returns 201 with a
verified boolean and an errors array, whether the credential is
valid or not — a malformed or invalid credential is a successful
API call that reports failure, not an HTTP error. Audited either
way (PRD §5.8's "pass/fail + reason").
Credentials carrying a credentialStatus entry additionally get a
revocation check after signature verification, and it fails closed:
a flipped bit yields revoked, and a status list that cannot be
fetched or signature-verified yields status_unavailable — both
are verification failures, since "could not determine revocation
state" must not read as "valid". The platform's own lists are read
locally; third-party lists are fetched over HTTP and
signature-verified before a single bit is trusted.
| credential required | string non-empty The wire credential to verify — compact JWT ( |
{- "credential": "string"
}{- "verified": true,
- "format": "vc+jwt",
- "errors": [
- {
- "code": "signature_invalid",
- "message": "string"
}
], - "credential": {
- "id": "string",
- "orgId": "string",
- "templateId": "string",
- "issuerId": "string",
- "issuerCertificate": {
- "orgId": "25b2c2d5-a7fc-47d0-89e4-8709a1560bfa",
- "chain": [
- "string"
], - "leaf": {
- "subject": "string",
- "serialNumber": "string",
- "fingerprintSha256": "string",
- "spkiSha256": "string",
- "notBefore": "2019-08-24T14:15:22Z",
- "notAfter": "2019-08-24T14:15:22Z"
}, - "trustAnchor": {
- "subject": "string",
- "fingerprintSha256": "string",
- "spkiSha256": "string"
}
}, - "subjectClaims": { },
- "validFrom": "2019-08-24T14:15:22Z",
- "validUntil": "2019-08-24T14:15:22Z"
}
}Bitstring Status List v1.0 revocation (PRD §5.6, Architecture §4).
Templates that declare revocable: true get a
status entry allocated at issuance and a credentialStatus object
embedded in the rendered credential (vc+jwt and vc20 formats).
Revocation flips the credential's bit; verification then reports
revoked.
The status list itself is served publicly at the host root (not under
/api), because its URL is baked verbatim into issued credentials as
statusListCredential and any relying party must be able to fetch it:
GET /status-lists/{orgId}/{listId} — the signed status list
(W3C BitstringStatusList, served as a Verifiable Credential; used by
vc+jwt and vc20)GET /token-status-lists/{orgId}/{listId} — the IETF Token Status
List, served as a statuslist+jwt; used by dc+sd-jwt, whose own
specification requires this mechanism rather than the W3C one
credential, a W3C VC 2.0 secured as a JWT (verifiable exactly like
any vc20 credential this platform issues). Reveals only bit
positions — never which credential or subject an index belongs to.API-key-authenticated (issue scope — the key that may create an
org's credentials is the one that may end them; a verify-only key
can do neither). Flips the credential's bit on its status list and
stamps revokedAt, in one transaction, audited as
credential.revoked. Idempotent: revoking an already-revoked
credential returns the original revocation without a second audit
event. Only credentials whose template declared revocable: true
can be revoked — anything else can only expire.
| credentialId required | string <uuid> |
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "revoked": true,
- "revokedAt": "2019-08-24T14:15:22Z"
}Console-facing counterpart to Revocation's /credentials/{id}/revoke
— same underlying mechanism, admin-session-authenticated instead of
API-key-authenticated, plus list and suspend/reactivate.
Suspend is reversible (card-block-style) and reachable only for
dc+sd-jwt credentials (IETF Token Status List, whose 2-bit field
has room for it) — W3C BitstringStatusList (vc+jwt/vc20) is
1-bit and has no suspended state, so suspending one of those is
rejected. Revoke remains permanent for every format; a revoked
credential can never be suspended or reactivated.
Admin and auditor. Newest first, offset pagination (follow
hasMore, same contract as GET .../audit-events). status is
computed from revokedAt/suspendedAt, not a stored column.
| orgId required | string <uuid> |
| templateId | string <uuid> |
| status | string Enum: "active" "revoked" "suspended" |
| limit | integer [ 1 .. 200 ] Default: 50 |
| offset | integer >= 0 Default: 0 |
{- "credentials": [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "templateId": "196100ac-4eec-4fb6-a7f7-86c8b584771d",
- "format": "string",
- "subjectClaims": { },
- "issuedAt": "2019-08-24T14:15:22Z",
- "validFrom": "2019-08-24T14:15:22Z",
- "validUntil": "2019-08-24T14:15:22Z",
- "revokedAt": "2019-08-24T14:15:22Z",
- "suspendedAt": "2019-08-24T14:15:22Z"
}
], - "limit": 0,
- "offset": 0,
- "hasMore": true
}Admin-only. Same underlying mechanism as
POST /credentials/{id}/revoke (Revocation tag) — permanent,
idempotent, audited as credential.revoked with actorType: user
instead of api_key.
| orgId required | string <uuid> |
| credentialId required | string <uuid> |
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "revoked": true,
- "revokedAt": "2019-08-24T14:15:22Z"
}Admin-only. Reversible (unlike revoke) — only for dc+sd-jwt
credentials; rejected for vc+jwt/vc20 (no suspended state in
BitstringStatusList). Rejected if the credential is already
revoked. Idempotent if already suspended.
| orgId required | string <uuid> |
| credentialId required | string <uuid> |
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "suspended": true,
- "suspendedAt": "2019-08-24T14:15:22Z"
}Admin-only. Rejected if the credential is not currently suspended, or if it has been revoked (permanent — cannot be undone this way).
| orgId required | string <uuid> |
| credentialId required | string <uuid> |
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "suspended": true,
- "suspendedAt": "2019-08-24T14:15:22Z"
}Readable by admin and auditor members — the auditor role is the
PRD §4 compliance persona, and this endpoint is what it exists for.
Newest-first, offset-paginated; hasMore is computed by fetching
one extra row, not by counting an append-only table. Rows are
immutable at the database layer (the app role has no UPDATE/DELETE
grants on audit_events).
| orgId required | string <uuid> |
| action | string Exact match on the dotted action, e.g. |
| resourceType | string e.g. |
| from | string <date-time> Inclusive lower bound on the event timestamp. |
| to | string <date-time> Exclusive upper bound on the event timestamp. |
| limit | integer [ 1 .. 200 ] Default: 50 |
| offset | integer >= 0 Default: 0 |
{- "events": [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "orgId": "25b2c2d5-a7fc-47d0-89e4-8709a1560bfa",
- "actorType": "user",
- "actorId": "d2f1b55c-8cee-4a0d-af57-aebaeff77518",
- "action": "string",
- "resourceType": "string",
- "resourceId": "string",
- "detail": { },
- "createdAt": "2019-08-24T14:15:22Z"
}
], - "limit": 0,
- "offset": 0,
- "hasMore": true
}Daily usage metering per organization (PRD §5.7) — credentials issued,
verifications, and API calls. Counts only; there is no invoicing or
payment surface. Credential counters are fed asynchronously from the
same events the audit trail records, so they can lag it by a few
seconds; api.call counts every successfully authenticated API-key
request.
Readable by admin and billing. Daily counters in UTC days,
defaulting to a trailing 30-day window. Days with no activity are
omitted, as are metrics with no activity on a given day.
| orgId required | string <uuid> |
| from | string <date> Inclusive lower bound (ISO date). Defaults to 29 days before |
| to | string <date> Inclusive upper bound (ISO date). Defaults to today (UTC). |
{- "from": "2019-08-24",
- "to": "2019-08-24",
- "days": [
- {
- "day": "2019-08-24",
- "counts": {
- "property1": 0,
- "property2": 0
}
}
], - "totals": {
- "property1": 0,
- "property2": 0
}
}Outbound HTTP callbacks when credentials are issued, verified or revoked (PRD §5.9).
Each delivery is a POST whose body is
{ id, topic, orgId, occurredAt, data } and which carries three
headers: X-VCP-Topic, X-VCP-Delivery-Id (stable across retries —
deduplicate on it), and X-VCP-Signature.
Verifying the signature. X-VCP-Signature has the form
t=<unix-seconds>,v1=<hex>, where v1 is
HMAC-SHA256(secret, "<t>.<raw-body>"). Compute it over the raw
request body before any JSON parsing, compare in constant time, and
reject timestamps outside your tolerance — t is inside the signed
material, so it cannot be rewritten without invalidating the
signature. The secret is returned exactly once, when the subscription
is created or its secret rotated.
Delivery is at-least-once. Failures retry with backoff (1m, 5m, 30m, 2h, 6h) and are then marked failed; every attempt is visible in the delivery log. Targets must be public HTTPS endpoints — addresses that resolve to private or link-local ranges are rejected.
Admin-only. Signing secrets are never returned — see the create and rotate operations.
| orgId required | string <uuid> |
[- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "topics": [
- "credential.issued"
], - "description": "string",
- "enabled": true,
- "createdBy": "25a02396-1048-48f9-bf93-102d2fb7895e",
- "createdAt": "2019-08-24T14:15:22Z",
- "updatedAt": "2019-08-24T14:15:22Z"
}
]Admin-only. Returns the signing secret exactly once, in this response — store it now; it cannot be read back, only rotated.
The target must be a public HTTPS URL. Hostnames are resolved and rejected if they point at loopback, private, CGNAT or link-local addresses, so a subscription cannot be used to probe the platform's own network.
| orgId required | string <uuid> |
| url required | string <uri> Public HTTPS endpoint. Private and link-local targets are rejected. |
| topics required | Array of strings (WebhookTopic) non-empty Items Enum: "credential.issued" "credential.verified" "credential.revoked" |
| description | string <= 200 characters |
{- "topics": [
- "credential.issued"
], - "description": "string"
}{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "topics": [
- "credential.issued"
], - "description": "string",
- "enabled": true,
- "createdBy": "25a02396-1048-48f9-bf93-102d2fb7895e",
- "createdAt": "2019-08-24T14:15:22Z",
- "updatedAt": "2019-08-24T14:15:22Z",
- "secret": "whsec_8Kj2mNp4qRs7tVw9xYz1AbCd"
}Admin-only. Newest first. Offset pagination with a hasMore flag
rather than a total count — follow hasMore, not arithmetic on a
total.
| orgId required | string <uuid> |
| subscriptionId | string <uuid> |
| status | string (WebhookDeliveryStatus) Enum: "pending" "delivering" "succeeded" "failed" |
| limit | integer [ 1 .. 200 ] Default: 50 |
| offset | integer >= 0 Default: 0 |
{- "deliveries": [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "subscriptionId": "d079718b-ff63-45dd-947b-4950c023750f",
- "topic": "credential.issued",
- "status": "pending",
- "attempts": 0,
- "responseStatus": 0,
- "lastError": "string",
- "nextAttemptAt": "2019-08-24T14:15:22Z",
- "createdAt": "2019-08-24T14:15:22Z",
- "deliveredAt": "2019-08-24T14:15:22Z"
}
], - "limit": 0,
- "offset": 0,
- "hasMore": true
}Admin-only, partial update. Setting enabled to false pauses
deliveries without discarding the subscription or its secret.
| orgId required | string <uuid> |
| id required | string <uuid> |
| url | string <uri> |
| topics | Array of strings (WebhookTopic) non-empty Items Enum: "credential.issued" "credential.verified" "credential.revoked" |
| description | string <= 200 characters |
| enabled | boolean False pauses deliveries; the subscription and its secret survive. |
{- "topics": [
- "credential.issued"
], - "description": "string",
- "enabled": true
}{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "topics": [
- "credential.issued"
], - "description": "string",
- "enabled": true,
- "createdBy": "25a02396-1048-48f9-bf93-102d2fb7895e",
- "createdAt": "2019-08-24T14:15:22Z",
- "updatedAt": "2019-08-24T14:15:22Z"
}Admin-only. Returns the new secret exactly once. Rotation takes effect immediately: deliveries queued but not yet sent are signed with the new secret, so update your receiver before rotating if you cannot tolerate rejected deliveries.
| orgId required | string <uuid> |
| id required | string <uuid> |
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "topics": [
- "credential.issued"
], - "description": "string",
- "enabled": true,
- "createdBy": "25a02396-1048-48f9-bf93-102d2fb7895e",
- "createdAt": "2019-08-24T14:15:22Z",
- "updatedAt": "2019-08-24T14:15:22Z",
- "secret": "whsec_8Kj2mNp4qRs7tVw9xYz1AbCd"
}This org's Wallet-Relying Party trust material (ARF, per-org): an RPAC (ETSI TS 119 411-8) proves who the RP is and signs OpenID4VP JAR requests; an RPRC (ETSI TS 119 475), optional, states what the RP may request.
Getting a real RPAC has two steps. First, generate a CSR — this mints a keypair and returns a PEM CSR to submit to a real registrar/QTSP. The CSR is shown once; if it's lost before being copied, generate a new one (the abandoned key is harmless). Second, once the registrar issues the certificate, import it — a PEM chain (leaf first, plus any intermediates), checked against the CSR this same org generated.
An RPRC has no CSR step — it's a self-contained JWT the registrar
issues and signs itself, imported directly. Its
organizationIdentifier must match the org's current RPAC.
Admin-only. One fetch for the whole screen: the current RPAC (if any), the current RPRC (if any), and a pending RPAC CSR (if one was generated but not yet imported).
| orgId required | string <uuid> |
{- "rpac": {
- "organizationIdentifier": "string",
- "source": "sandbox-self-signed",
- "certificateChainPem": "string",
- "notBefore": "2019-08-24T14:15:22Z",
- "notAfter": "2019-08-24T14:15:22Z"
}, - "rprc": {
- "jwt": "string",
- "organizationIdentifier": "string",
- "source": "sandbox-self-signed",
- "notBefore": "2019-08-24T14:15:22Z",
- "notAfter": "2019-08-24T14:15:22Z"
}, - "pendingRpacCsr": {
- "organizationIdentifier": "string",
- "createdAt": "2019-08-24T14:15:22Z"
}
}Admin-only. Mints a keypair and returns a PEM PKCS#10 CSR naming
organizationIdentifier, for manual submission to a real
registrar/QTSP. Replaces any previously generated, not-yet-imported
CSR for this org — the abandoned key is harmless.
| orgId required | string <uuid> |
| organizationIdentifier required | string <= 200 characters |
{- "organizationIdentifier": "string"
}{- "csrPem": "string"
}Admin-only. organizationIdentifier must match the org's pending
CSR (400 otherwise — including when there is no pending CSR at
all). certificateChainPem is one or more concatenated
-----BEGIN CERTIFICATE----- blocks, leaf first.
| orgId required | string <uuid> |
| organizationIdentifier required | string <= 200 characters Must match the pending CSR's — rejected otherwise. |
| certificateChainPem required | string PEM, one or more concatenated certificate blocks, leaf first. |
{- "organizationIdentifier": "string",
- "certificateChainPem": "string"
}{- "organizationIdentifier": "string",
- "source": "sandbox-self-signed",
- "certificateChainPem": "string",
- "notBefore": "2019-08-24T14:15:22Z",
- "notAfter": "2019-08-24T14:15:22Z"
}Admin-only. No CSR step — an RPRC is a self-contained JWT the
registrar issues and signs itself, stored verbatim.
organizationIdentifier must match the org's current RPAC, if one
is active (400 otherwise).
| orgId required | string <uuid> |
| jwt required | string |
| organizationIdentifier required | string <= 200 characters Must match the org's current RPAC, if one is active — rejected otherwise. |
{- "jwt": "string",
- "organizationIdentifier": "string"
}{- "jwt": "string",
- "organizationIdentifier": "string",
- "source": "sandbox-self-signed",
- "notBefore": "2019-08-24T14:15:22Z",
- "notAfter": "2019-08-24T14:15:22Z"
}The X.509 trust anchors of issuers outside the platform (an EUDI PID provider, an mDL issuing authority, a partner) whose credentials this org's presentation requests may accept. Per org: an anchor affects only requests of the org that added it, and only those that name it. Kept apart from the platform's own issuer trust, so an outside CA can never vouch for a credential that claims to come from an organisation on the platform.
Admin-only. Every anchor, with enough of each certificate to recognise
it. A presentation request names the ones it accepts by id in
credentials[].issuer.trustAnchorIds.
| orgId required | string <uuid> |
[- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "label": "string",
- "subject": "string",
- "issuer": "string",
- "serialNumber": "string",
- "fingerprintSha256": "string",
- "spkiSha256": "string",
- "ca": true,
- "selfSigned": true,
- "notBefore": "2019-08-24T14:15:22Z",
- "notAfter": "2019-08-24T14:15:22Z",
- "expired": true,
- "createdAt": "2019-08-24T14:15:22Z"
}
]Admin-only. certificate is one X.509 certificate, as PEM or base64
DER, that can certify keys: a CA (basicConstraints CA:TRUE) or a
self-signed root. Rejected (400) if it is not exactly one certificate,
has expired, is an end-entity certificate, or the label is blank; 409
if the org already has that certificate or that label (labels compare
case-insensitively). An org can have at most 50.
Adding an anchor lets anyone holding a key it certifies issue credentials this org accepts, in requests that name the anchor. It never affects credentials issued on the platform, which are checked against the platform's own issuer keys.
| orgId required | string <uuid> |
| label required | string <= 80 characters A name for the list, unique per org (case-insensitively). |
| certificate required | string <= 20000 characters PEM or base64 DER of exactly one X.509 CA or self-signed root certificate. |
{- "label": "string",
- "certificate": "string"
}{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "label": "string",
- "subject": "string",
- "issuer": "string",
- "serialNumber": "string",
- "fingerprintSha256": "string",
- "spkiSha256": "string",
- "ca": true,
- "selfSigned": true,
- "notBefore": "2019-08-24T14:15:22Z",
- "notAfter": "2019-08-24T14:15:22Z",
- "expired": true,
- "createdAt": "2019-08-24T14:15:22Z"
}Admin-only. Takes effect at once, including for requests already created: verification re-reads the anchors a request names.
| orgId required | string <uuid> |
| anchorId required | string <uuid> |
{- "statusCode": 0,
- "error": "string",
- "message": "string"
}Which Wallet Providers this org's issuance endpoints believe. A wallet proves what it is with a client attestation (at PAR and the token endpoint) and, for a credential that requires one, a key attestation (in the credential request's proof); both are signed by its Wallet Provider, and are accepted only if that signature chains to a certificate listed here. In ARF terms these are the Wallet Providers an Attestation Provider accepts.
The platform's own reference Wallet Provider (the one behind the reference wallets) is on the list by default, registered automatically the first time it is needed. Add another provider's attestation-signing CA, or a pinned signing certificate, to accept that provider's wallets. Turn the reference provider off to stop accepting it for this org; its row stays listed, since removing it would only have it registered again.
Admin-only, reads included. Adding an entry lets another provider's
wallets authenticate to this org, so every change is audited
(wallet_provider.added, wallet_provider.removed,
wallet_provider.reference_trust_changed).
Admin-only. Every trust anchor, the reference provider's included
(reference: true), with enough of each certificate to recognise it.
referenceProviderTrusted says whether the reference provider is
accepted for this org; referenceProviderAvailable whether this
deployment runs one at all.
| orgId required | string <uuid> |
{- "referenceProviderTrusted": true,
- "referenceProviderAvailable": true,
- "providers": [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "label": "string",
- "reference": true,
- "subject": "string",
- "issuer": "string",
- "serialNumber": "string",
- "fingerprintSha256": "string",
- "ca": true,
- "notBefore": "2019-08-24T14:15:22Z",
- "notAfter": "2019-08-24T14:15:22Z",
- "expired": true,
- "createdAt": "2019-08-24T14:15:22Z"
}
]
}Admin-only. certificate is one X.509 certificate, as PEM or base64
DER: the provider's attestation-signing CA, or a pinned signing
certificate. Rejected (400) if it is not exactly one certificate, has
expired, or the label is blank or reserved; 409 if the org already
trusts that certificate or has a provider with that label (labels
compare case-insensitively). An org can trust at most 20.
| orgId required | string <uuid> |
| label required | string <= 80 characters A name for the list, unique per org (case-insensitively). |
| certificate required | string <= 20000 characters PEM or base64 DER of exactly one X.509 certificate. |
{- "label": "string",
- "certificate": "string"
}{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "label": "string",
- "reference": true,
- "subject": "string",
- "issuer": "string",
- "serialNumber": "string",
- "fingerprintSha256": "string",
- "ca": true,
- "notBefore": "2019-08-24T14:15:22Z",
- "notAfter": "2019-08-24T14:15:22Z",
- "expired": true,
- "createdAt": "2019-08-24T14:15:22Z"
}Admin-only. trusted: false makes this org stop accepting the
reference provider's attestations and stops it being registered
again, including before it was ever registered. It works whether or
not the reference provider's row exists and survives its certificate
changing. trusted: true restores the default.
| orgId required | string <uuid> |
| trusted required | boolean |
{- "trusted": true
}{- "referenceProviderTrusted": true,
- "referenceProviderAvailable": true,
- "providers": [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "label": "string",
- "reference": true,
- "subject": "string",
- "issuer": "string",
- "serialNumber": "string",
- "fingerprintSha256": "string",
- "ca": true,
- "notBefore": "2019-08-24T14:15:22Z",
- "notAfter": "2019-08-24T14:15:22Z",
- "expired": true,
- "createdAt": "2019-08-24T14:15:22Z"
}
]
}Admin-only. Removes a provider an admin added; wallets it vouched for
can no longer authenticate to this org. The reference provider cannot
be removed (400), only switched off with
PUT /orgs/{orgId}/wallet-providers/reference.
| orgId required | string <uuid> |
| providerId required | string <uuid> |
{- "statusCode": 0,
- "error": "string",
- "message": "string"
}The configurable half of this org's OpenID4VP/SCA verification checks — everything else (issuer trust, revocation status) is hardcoded, not policy. All three fields are optional; omitted means "use the default," and an org that never calls this endpoint gets exactly today's behavior.
iatWindowSeconds bounds how old a presentation's key-binding JWT
may be (null/omitted: unbounded, no check). minAmrCategories
raises TS12 §3.6's own floor of 2 distinct authentication categories
— it can never be set below that floor. allowedTransactionDataTypes
restricts which transaction_data.type values this org's own
backend may request when creating a presentation request (null/
omitted: unrestricted, any type build-transaction-data can encode).
No trusted-issuer allowlist: this org's verifier only ever accepts credentials issued by itself today, so one would have no effect until third-party-requested verification ships.
Admin-only. Always returns a full policy, even for an org that has
never configured one — updatedAt: null distinguishes "defaults,
never set" from "explicitly set to these values."
| orgId required | string <uuid> |
{- "iatWindowSeconds": 0,
- "minAmrCategories": 0,
- "allowedTransactionDataTypes": [
- "string"
], - "updatedAt": "2019-08-24T14:15:22Z"
}Admin-only, partial update — an omitted field is left unchanged.
null explicitly resets iatWindowSeconds/allowedTransactionDataTypes
to unrestricted; an empty array is rejected for
allowedTransactionDataTypes (ambiguous between "unrestricted" and
"allow nothing"). minAmrCategories below 2 is rejected outright —
that floor is a TS12 §3.6 conformance requirement, not a preference.
| orgId required | string <uuid> |
| iatWindowSeconds | integer or null [ 1 .. 3600 ] |
| minAmrCategories | integer [ 2 .. 10 ] |
| allowedTransactionDataTypes | Array of strings or null non-empty |
{- "iatWindowSeconds": 1,
- "minAmrCategories": 2,
- "allowedTransactionDataTypes": [
- "string"
]
}{- "iatWindowSeconds": 0,
- "minAmrCategories": 0,
- "allowedTransactionDataTypes": [
- "string"
], - "updatedAt": "2019-08-24T14:15:22Z"
}OpenID4VCI 1.0 Final issuance (PRD §5.4, Architecture §4). Only offer
creation lives under /api — the wallet-facing protocol endpoints sit at
the host root, because every org is its own credential issuer at
{publicUrl}/oid4vci/{orgId}. Two grant types are supported, both
requiring Wallet Instance Attestation: the pre-authorized code flow
below (no PAR, no DPoP, but client attestation required since the
pre-authorized_code Wallet Attestation CR gave it parity with
authorization_code), and, since Phase 2, a full authorization_code
flow gated by PAR, PKCE, a real browser login, client attestation and
DPoP — see AUTHORIZED_FLOW_ARCHITECTURE.md for the wire-level detail
this section deliberately doesn't repeat:
GET /.well-known/openid-credential-issuer/oid4vci/{orgId} — issuer metadataGET /.well-known/oauth-authorization-server/oid4vci/{orgId} — AS metadataGET /oid4vci/{orgId}/jwks — org public key set (access-token verification)POST /oid4vci/{orgId}/par — RFC 9126 pushed authorization request;
starts the authorization_code grant (not used by the
pre-authorized-code grant)GET /oid4vci/{orgId}/authorize — the browser lands here after PAR;
completes silently if a login session cookie already covers this
org, otherwise renders a minimal login formPOST /oid4vci/{orgId}/authorize — the login form's submit target;
redirects the browser back to the wallet with an authorization codePOST /oid4vci/{orgId}/token — exchanges either grant
(pre-authorized code, or the authorization code from the flow above)
for an access token; both require a Client Attestation JWT
(OAuth-Client-Attestation/-PoP headers) — anonymous requests are
rejected on both grantsPOST /oid4vci/{orgId}/nonce — c_nonce endpoint (Final's dedicated nonce endpoint);
Cache-Control: no-store, like the token, PAR and credential responsesPOST /oid4vci/{orgId}/credential — proof-of-possession → SD-JWT VC.
The response carries the credential as Final's
credentials: [{ "credential": … }] and, until the deployed wallets
have moved, also as the pre-Final credential. Unknown
credential_configuration_id → unknown_credential_configuration;
any credential_identifier → unknown_credential_identifier (this
issuer hands none out)POST /oid4vci/{orgId}/notification — wallet reports what it did
with the issued credential (credential_accepted /
credential_failure / credential_deleted), same access token as
the credential endpoint. Optional per spec; when a wallet sends
credential_accepted, GET /credentials/offers/{offerId} reports
confirmed instead of accepted.Wire formats for those are defined by the OpenID4VCI / OAuth2 specs,
not re-documented here; conforming wallets discover everything from
the credential offer URI returned by POST /credentials/offers.
Client Attestation and Key Attestation issuance — what a wallet
needs before it can even reach the endpoints above — used to be
documented here as prose under this file's own Attestations/
Key Attestations tags. Both moved to apps/wallet-backend/docs/openapi.yaml
when that issuance surface was carved out into its own deployable for
security isolation (Client/Key Attestation are the only fully
unauthenticated, pre-auth routes anywhere on this system) — see the
Wallet Backend API reference, linked from
this site's sidebar, for the full contract.
Starts the OpenID4VCI pre-authorized code flow: the org's backend
(API key, issue scope) states what to issue; the response's
credentialOffer URI goes to the holder as a QR code / deep link,
and their wallet drives the rest against the wallet-facing endpoints
(see the OpenID4VCI tag). The offer expires after expiresIn
seconds, the pre-authorized code is single-use, and the credential
is bound to the wallet's proof-of-possession key (cnf) at the
credential endpoint — subject claims are fixed here, at offer time.
| templateId required | string <uuid> |
| subjectClaims required | object Fixed at offer time — the wallet receives exactly these claims. For a template with |
| format | string Default: "dc+sd-jwt" Enum: "vc+jwt" "vc11+ld" "vc20" "dc+sd-jwt" "mso_mdoc" Defaults to dc+sd-jwt. dc+sd-jwt and mso_mdoc are both
OpenID4VCI-offerable; vc+jwt, vc20, and vc11+ld are issued
only via the direct POST /credentials endpoint, not as an
OpenID4VCI offer. Must also be listed in the template's own
|
{- "templateId": "196100ac-4eec-4fb6-a7f7-86c8b584771d",
- "subjectClaims": { },
- "format": "dc+sd-jwt"
}{- "credentialOffer": "string",
- "credentialOfferObject": { },
- "expiresIn": 0,
- "offerId": "42da58f8-9040-4cf5-98ce-bce9965cca0d"
}Requires an API key with the issue scope — same requirement as creating the offer.
| offerId required | string <uuid> |
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "status": "pending",
- "credentialId": "f568fec0-10b6-4b94-9daf-e62c50c9bf3e",
- "holderKeyId": "string",
- "error": "attestation_required"
}OpenID4VP 1.0 Final relying-party flow with DCQL (PRD §5.5,
Architecture §4). The org's backend creates a presentation request —
by default JAR-signed (RFC 9101) with this platform's ACME verifier
certificate, x509_hash client-id scheme (HAIP 1.0 §5), delivered via
request_uri; pass signed: false for the unsigned, by-value,
redirect_uri client-id form instead — shows the returned
openid4vp:// URI to the holder, and polls the request for the
outcome. Two more opt-in knobs on the same request, both independent
of signed: trustModel: 'rpac' signs under the EUDI ARF
Relying-Party trust model (ETSI TS 119 411-8) instead of the default
ACME/web-pki anchor and attaches an RPRC via verifier_info
(ETSI TS 119 475, sandbox-only); jarm: true has the wallet answer
encrypted, direct_post.jwt, instead of plain direct_post —
encrypt-only (an unsigned JWT, encrypted), per OpenID4VP 1.0's own
definition, not the generic JARM spec's sign-and-encrypt option it
replaced. See CreatePresentationRequest for both. The wallet
answers by direct_post (or direct_post.jwt if jarm) to the
wallet-facing endpoint at the host root:
POST /oid4vp/{orgId}/response/{requestId} — authorization response
(vp_token with DCQL-keyed SD-JWT VC presentations)Presentations must carry a key-binding JWT: its signature is checked
against the credential's cnf key, and its nonce/aud must match this
exact request — a presentation captured from one exchange cannot be
replayed into another.
Starts an OpenID4VP exchange (API key, verify scope): names the
credential type(s) being asked for (by template) and optionally
which claims the wallet should disclose. Poll the returned id for
the outcome; the request expires after expiresIn seconds. Asking
for several credentials at once (credentials) still produces one
URI, one wallet screen, one response.
| templateId | string <uuid> Template whose credential type is being asked for. For
dc+sd-jwt, vct = the template name; for mso_mdoc, docType =
the template name. Mutually exclusive with |
| format | string Default: "dc+sd-jwt" Enum: "vc+jwt" "vc11+ld" "vc20" "dc+sd-jwt" "mso_mdoc" Defaults to dc+sd-jwt. dc+sd-jwt and mso_mdoc are both
presentable; must also be listed in the template's own
|
| requestedClaims | Array of strings Claim names the wallet is asked to disclose. Omitted = the
wallet decides. Only used with |
| signed | boolean Default: true JAR-sign the request (RFC 9101) with this platform's ACME
verifier certificate, |
| trustModel | string Default: "web-pki" Enum: "web-pki" "rpac" Which certificate authenticates this request's JAR signature,
when |
| jarm | boolean Default: false Request the wallet deliver its authorization response encrypted
( |
| redirectUri | string <uri> Same-device flow (HAIP 1.0 §5.1, OpenID4VP 1.0 §8.2): the page the
wallet sends the user back to after posting its response. The
wallet is answered with |
| dcApiOrigin | string Deliver the request over the W3C Digital Credentials API
(OpenID4VP 1.0 Appendix A) instead of an The browser attests this origin to the wallet, and every
presentation is bound to it: the KB-JWT |
| dcApiProtocols | Array of strings non-empty unique Items Enum: "openid4vp" "org-iso-mdoc" Which DC API protocols to offer, in order of preference; the
browser uses the first one a wallet on the device supports. Only
with
When this field is given, the response lists every request in
|
Array of objects [ 1 .. 10 ] items Ask for several credentials in one request: one openid4vp://
URI, one wallet claim-selection screen, one direct_post
response. Every entry is mandatory — the exchange only
verifies once the wallet has answered all of them. Mutually
exclusive with the top-level |
{- "templateId": "196100ac-4eec-4fb6-a7f7-86c8b584771d",
- "format": "dc+sd-jwt",
- "requestedClaims": [
- "string"
], - "signed": true,
- "trustModel": "web-pki",
- "jarm": false,
- "dcApiProtocols": [
- "org-iso-mdoc",
- "openid4vp"
], - "credentials": [
- {
- "id": "string",
- "templateId": "196100ac-4eec-4fb6-a7f7-86c8b584771d",
- "vct": "string",
- "docType": "string",
- "namespace": "string",
- "issuer": {
- "orgId": "25b2c2d5-a7fc-47d0-89e4-8709a1560bfa",
- "trustAnchorIds": [
- "497f6eca-6276-4993-bfeb-53cbbbba6f08"
]
}, - "format": "dc+sd-jwt",
- "requestedClaims": [
- "string"
]
}
]
}{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "authorizationRequest": "string",
- "expiresIn": 0
}Requires an API key with the verify scope — same requirement as creating the request.
| requestId required | string <uuid> |
| responseCode | string Same-device requests ( |
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "status": "pending",
- "responseCodeRequired": true,
- "vct": "string",
- "templateId": "196100ac-4eec-4fb6-a7f7-86c8b584771d",
- "result": {
- "verified": true,
- "disclosedClaims": { },
- "issuerId": "string",
- "trustAnchorId": "3b23991c-8f8d-4c31-af5f-dfca98404c51",
- "issuerCertificate": {
- "orgId": "25b2c2d5-a7fc-47d0-89e4-8709a1560bfa",
- "chain": [
- "string"
], - "leaf": {
- "subject": "string",
- "serialNumber": "string",
- "fingerprintSha256": "string",
- "spkiSha256": "string",
- "notBefore": "2019-08-24T14:15:22Z",
- "notAfter": "2019-08-24T14:15:22Z"
}, - "trustAnchor": {
- "subject": "string",
- "fingerprintSha256": "string",
- "spkiSha256": "string"
}
}, - "holderKeyId": "string",
- "validUntil": "2019-08-24T14:15:22Z",
- "errors": [
- {
- "code": "signature_invalid",
- "message": "string"
}
]
}, - "results": [
- {
- "id": "string",
- "vct": "string",
- "templateId": "196100ac-4eec-4fb6-a7f7-86c8b584771d",
- "issuerOrgId": "be922628-dcbc-4925-9bc4-b1d8220850e7",
- "trustAnchorIds": [
- "497f6eca-6276-4993-bfeb-53cbbbba6f08"
], - "result": {
- "verified": true,
- "disclosedClaims": { },
- "issuerId": "string",
- "trustAnchorId": "3b23991c-8f8d-4c31-af5f-dfca98404c51",
- "issuerCertificate": {
- "orgId": "25b2c2d5-a7fc-47d0-89e4-8709a1560bfa",
- "chain": [
- "string"
], - "leaf": {
- "subject": "string",
- "serialNumber": "string",
- "fingerprintSha256": "string",
- "spkiSha256": "string",
- "notBefore": "2019-08-24T14:15:22Z",
- "notAfter": "2019-08-24T14:15:22Z"
}, - "trustAnchor": {
- "subject": "string",
- "fingerprintSha256": "string",
- "spkiSha256": "string"
}
}, - "holderKeyId": "string",
- "validUntil": "2019-08-24T14:15:22Z",
- "errors": [
- {
- "code": "signature_invalid",
- "message": "string"
}
]
}
}
]
}Only for requests created with dcApiOrigin (OpenID4VP 1.0
Appendix A). Over the DC API the browser hands the wallet's answer
to your page, not to this platform, so your backend forwards it
here: the data member of the DigitalCredential that
navigator.credentials.get() resolved with, verbatim —
{ "response": "<JWE>" }, or { "error": "..." } when the wallet
returned a protocol error (the DC API resolves, rather than
rejects, in that case). Requires the verify scope.
For an org-iso-mdoc answer (ISO/IEC TS 18013-7 Annex C) response
is the base64url CBOR ["dcapi", { enc, cipherText }] the wallet
encrypted to the request's EncryptionInfo key. Add protocol
(DigitalCredential.protocol) so the platform knows which
protocol is answering; it is optional when the request offered one
protocol, and otherwise inferred from the shape of response.
Answers 200 with the same body as polling, whether or not the
presentation verified — check status. A request can be completed
once; its result stays pollable until it expires.
| requestId required | string <uuid> |
| response | string The encrypted authorization response ( |
| error | string A wallet-side OpenID4VP error code (§8.5), reported back as |
| error_description | string |
| protocol | string
|
{- "response": "string",
- "error": "string",
- "error_description": "string",
- "protocol": "string"
}{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "status": "pending",
- "responseCodeRequired": true,
- "vct": "string",
- "templateId": "196100ac-4eec-4fb6-a7f7-86c8b584771d",
- "result": {
- "verified": true,
- "disclosedClaims": { },
- "issuerId": "string",
- "trustAnchorId": "3b23991c-8f8d-4c31-af5f-dfca98404c51",
- "issuerCertificate": {
- "orgId": "25b2c2d5-a7fc-47d0-89e4-8709a1560bfa",
- "chain": [
- "string"
], - "leaf": {
- "subject": "string",
- "serialNumber": "string",
- "fingerprintSha256": "string",
- "spkiSha256": "string",
- "notBefore": "2019-08-24T14:15:22Z",
- "notAfter": "2019-08-24T14:15:22Z"
}, - "trustAnchor": {
- "subject": "string",
- "fingerprintSha256": "string",
- "spkiSha256": "string"
}
}, - "holderKeyId": "string",
- "validUntil": "2019-08-24T14:15:22Z",
- "errors": [
- {
- "code": "signature_invalid",
- "message": "string"
}
]
}, - "results": [
- {
- "id": "string",
- "vct": "string",
- "templateId": "196100ac-4eec-4fb6-a7f7-86c8b584771d",
- "issuerOrgId": "be922628-dcbc-4925-9bc4-b1d8220850e7",
- "trustAnchorIds": [
- "497f6eca-6276-4993-bfeb-53cbbbba6f08"
], - "result": {
- "verified": true,
- "disclosedClaims": { },
- "issuerId": "string",
- "trustAnchorId": "3b23991c-8f8d-4c31-af5f-dfca98404c51",
- "issuerCertificate": {
- "orgId": "25b2c2d5-a7fc-47d0-89e4-8709a1560bfa",
- "chain": [
- "string"
], - "leaf": {
- "subject": "string",
- "serialNumber": "string",
- "fingerprintSha256": "string",
- "spkiSha256": "string",
- "notBefore": "2019-08-24T14:15:22Z",
- "notAfter": "2019-08-24T14:15:22Z"
}, - "trustAnchor": {
- "subject": "string",
- "fingerprintSha256": "string",
- "spkiSha256": "string"
}
}, - "holderKeyId": "string",
- "validUntil": "2019-08-24T14:15:22Z",
- "errors": [
- {
- "code": "signature_invalid",
- "message": "string"
}
]
}
}
]
}Logging into the console with a verifiable credential instead of Zitadel — a second front door onto the same account, not a replacement: an account must already exist (via Zitadel) and a credential must already be linked to it before login can succeed.
Both endpoint families follow the same create-request/poll shape as
OpenID4VP above, reusing the same openid4vp:// request/QR-code/
deep-link UX for both same-device (a browser extension) and
cross-device (a mobile wallet scanning the QR) presentation. The
wallet answers by direct_post to the same wallet-facing endpoint
shape as OpenID4VP, at the host root:
POST /oid4vp/login-response/{requestId} — authorization responseNo vct/docType is requested — either flow accepts whichever
credential (dc+sd-jwt or mso_mdoc) the wallet offers. What decides
acceptance is the credential's ID (its jti for dc+sd-jwt; a hash of
the holder's bound key for mso_mdoc, which has no jti-equivalent
claim) matching an entry already on a user profile — an unrecognized
credential is rejected outright, never auto-provisioned into a new
account. On a successful login, the disclosed name/email sync onto the
profile when they differ from what's stored.
Public — there is no session yet by definition. The body is optional (see CreateCredentialRequest).
| sameDevice | boolean Default: false The request will be opened in a wallet on this device, not shown as
a QR code. Where the deployment has
|
{- "sameDevice": false
}{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "authorizationRequest": "string",
- "expiresIn": 0,
- "redirect": true
}Public, same as creating it — the request id itself is the bearer capability. Once status is verified, accessToken/expiresIn carry the console's new session token.
| id required | string <uuid> |
| responseCode | string Same-device requests only — the |
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "status": "pending",
- "responseCodeRequired": true,
- "accessToken": "string",
- "expiresIn": 0,
- "claims": {
- "email": "string",
- "name": "string"
}, - "errors": [
- {
- "code": "string",
- "message": "string"
}
]
}Requires the existing Zitadel-backed console session
(ConsoleBearerAuth, the default for this page). Takes no body — the
target is always the authenticated caller, never a supplied user id.
Linking a new credential replaces any previously linked one. The
body is optional (see CreateCredentialRequest).
| sameDevice | boolean Default: false The request will be opened in a wallet on this device, not shown as
a QR code. Where the deployment has
|
{- "sameDevice": false
}{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "authorizationRequest": "string",
- "expiresIn": 0,
- "redirect": true
}Requires the same session that created the request — another caller's (or an unknown/expired) id reports 404, not 403, so as not to confirm a request id belongs to someone else.
| id required | string <uuid> |
| responseCode | string Same-device requests only — the |
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "status": "pending",
- "responseCodeRequired": true,
- "accessToken": "string",
- "expiresIn": 0,
- "claims": {
- "email": "string",
- "name": "string"
}, - "errors": [
- {
- "code": "string",
- "message": "string"
}
]
}An MCP (Model Context Protocol) server exposing agent-identity
operations as tools — AGENT_IDENTITY_MCP_PLAN.md's Slice A: an org's
own automation gets its own audit-attributable identity, not a new
agent-to-agent trust model. A single Streamable HTTP endpoint, not
modelled as formal paths for the same reason as OpenID4VCI/OpenID4VP
above — a client discovers everything (tool names, input schemas) via
the MCP protocol itself, not an OpenAPI schema:
POST /mcp — MCP Streamable HTTP transport (stateless: no session ID,
a fresh server per request). Authorization: Bearer <api key>, same
as every other API-key-authenticated route.Tools, each a thin wrapper over an already-built operation:
create_agent_identity — mints a platform-custodial key and issues
an AgentIdentityCredential under it. The template must be
revocable. Requires the admin scope.open_agent_session — the platform presents that credential on the
agent's behalf (KB-JWT signed by the signing service, not the
caller) and, once its own signature and nonce/aud/vct binding
verify, returns a short-lived session token. The session never
carries more scope than the API key that opened it. Requires admin.issue_credential / verify_credential — wrap POST /credentials
and POST /credentials/verify, but attribute the resulting audit
event to the agent (actorType: 'agent') instead of only the API
key, given a valid agentSessionToken whose session carries the
matching issue/verify scope.present_agent_identity — Slice B: presents the agent's credential
for an audience/nonce supplied by a real external relying party
(delivered to the caller out of band). Unlike open_agent_session,
the platform does not verify the result itself — the external party
does, using standard did:jwk/cnf.jwk/status-list checks, the
same as any other dc+sd-jwt credential this platform issues.
Requires admin.revoke_agent_identity — revokes an agent identity: blocks future
open_agent_session/present_agent_identity calls, and flips the
credential's real status-list entry (the same mechanism
POST /credentials/{id}/revoke uses) so an external relying party
checking independently sees the same answer. Requires admin.