VC Platform API (0.2.0)

Org creation and the caller's org list (PRD §5.1)

Org membership management, admin-gated except listing (PRD §5.1)

Org-scoped API key issuance, listing, and revocation (PRD §5.2)

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.

Issuance and verification, API-key-authenticated (PRD §5.4, §5.5)

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.

Read side of the append-only audit trail (PRD §5.8) — admin and auditor roles

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.

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.

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 metadata
• GET /.well-known/oauth-authorization-server/oid4vci/{orgId} — AS metadata
• GET /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 form
• POST /oid4vci/{orgId}/authorize — the login form's submit target; redirects the browser back to the wallet with an authorization code
• POST /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 grants
• POST /oid4vci/{orgId}/nonce — c_nonce endpoint (Final's dedicated nonce endpoint)
• POST /oid4vci/{orgId}/credential — proof-of-possession → SD-JWT VC
• 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.

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.

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 response

No 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.

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.