Skip to main content
Version: v0.25.0 (Latest)

REST API

The EDK exposes the credential design registry over HTTP under the base path /api/credential-design/v1. One adapter covers credential designs, issuer designs, verifier designs, render variants, imports, refreshes, resolution, source snapshots, and binary assets.

The full request and response schema for every operation is in the Credential Design API reference. The endpoints that list or find designs return a plain JSON array rather than a paginated page.

Credential designs​

A credential design holds the bindings a credential is matched by, its localized displays, the claim presentation (labels, ordering, selective disclosure policy), and the render variants it points at. Bindings are the protocol identifiers a credential is keyed on, set as an object rather than a key/value pair:

{
  "bindings": [
    { "vct": "https://issuer.example.com/identity", "credentialConfigurationId": "IdentityCredential" }
  ]
}

Each claim is addressed by a path, a list of polymorphic segments discriminated by type (property, index, or any). The path to given_name is [{ "type": "property", "name": "given_name" }]. sdPolicy is ALWAYS, ALLOWED, or NEVER; valueKind and widgetHint drive form rendering. The full field set is in the API reference.

Create a credential design​

Creates a credential design in the caller's tenant from its bindings, displays, and claims. Returns the stored CredentialDesignRecord with the server-assigned id, tenantId, and timestamps. Fails with 409 when a binding already maps to a design.

POST /api/credential-design/v1/designs/credentials

The full request and response schema is in the API reference, or open the API reference tab to read it inline.

List credential designs​

Returns every credential design in the tenant matching the optional query filters: entityType, hostingMode, bindingKey + bindingValue, aliasContains, and sourceType. Unknown enum values are ignored. The response is a plain array.

GET /api/credential-design/v1/designs/credentials

The full request and response schema is in the API reference, or open the API reference tab to read it inline.

Find credential designs by binding​

Finds the credential designs whose binding has a given value for one dimension, for example all designs bound to a VCT. The companion POST /designs/credentials/find/binding matches against a full binding object instead.

GET /api/credential-design/v1/designs/credentials/bindings/{bindingKey}/{bindingValue}

The full request and response schema is in the API reference, or open the API reference tab to read it inline.

Import a credential design​

Imports a design from an external source. The server fetches sourceUrl through an SSRF-protected fetcher, stores a source snapshot, runs the mapper for the declared sourceType (one of the DesignSourceType values, for example OID4VCI_CREDENTIAL_CONFIGURATION, SD_JWT_VCT_METADATA, or OCA_BUNDLE), and persists the canonical design with hostingMode set to CACHED_EXTERNAL.

POST /api/credential-design/v1/designs/credentials/import

The full request and response schema is in the API reference, or open the API reference tab to read it inline.

Resolve a credential design​

Resolves a design into its merged form: the design combined with its issuer and verifier designs, the matching render variants, derived render hints, the ordered list of applied source layers, the fields locked by authoritative layers, and an ETag for caching. Select the design by designId, a full binding, or a bindingKey + bindingValue pair. Pass external material inline through externalMetadata (for example an ocaBundle) to fold it into the result without importing first.

POST /api/credential-design/v1/designs/credentials/resolve

The full request and response schema is in the API reference, or open the API reference tab to read it inline.

Get a credential design​

Returns one credential design exactly as stored. To get the merged result with everything that contributes to it, use the resolve endpoint instead.

GET /api/credential-design/v1/designs/credentials/{designId}

The full request and response schema is in the API reference, or open the API reference tab to read it inline.

Update a credential design​

Updates a credential design. Every field on the body is optional; omitted fields are left unchanged.

PUT /api/credential-design/v1/designs/credentials/{designId}

The full request and response schema is in the API reference, or open the API reference tab to read it inline.

Delete a credential design​

Deletes a credential design, returning true when a design was removed.

DELETE /api/credential-design/v1/designs/credentials/{designId}

The full request and response schema is in the API reference, or open the API reference tab to read it inline.

Refresh an imported design​

Re-fetches an imported design from its source and re-applies the mapper, using the snapshot's ETag for a conditional request. Returns the updated design.

POST /api/credential-design/v1/designs/credentials/{designId}/refresh

The full request and response schema is in the API reference, or open the API reference tab to read it inline.

Issuer and verifier designs​

Issuer and verifier designs describe how the issuing or verifying party presents itself, matched by issuer or verifier identity bindings (issuerDid, issuerUri, verifierClientId). Their endpoints mirror the credential design set exactly under /designs/issuers and /designs/verifiers: create, list, find by binding, find by binding key, import, resolve, get, update, delete, and refresh. The request and response bodies are the same shape with the issuer or verifier record type, and the command ids follow the credential-design.issuers.* and credential-design.verifiers.* namespaces. A credential design links the issuer design it is issued under through issuerDesignId.

Create an issuer design​

Creates an issuer design. The verifier equivalent is POST /designs/verifiers (credential-design.verifiers.create), with the same body shape.

POST /api/credential-design/v1/designs/issuers

The full request and response schema is in the API reference, or open the API reference tab to read it inline.

Resolve an issuer design​

Resolves an issuer design selected by id or binding into its merged form with render variants, applied layers, and locked fields. The verifier equivalent is POST /designs/verifiers/resolve (credential-design.resolution.verifier-resolve).

POST /api/credential-design/v1/designs/issuers/resolve

The full request and response schema is in the API reference, or open the API reference tab to read it inline.

Render variants​

A render variant is a reusable rendering technique that designs point at: a simple card (colors plus a logo and background image), an SVG template, a W3C VC renderMethod reference, a PDF template, or an external reference. The kind field selects which, and the relevant fields are populated for that kind.

Create a render variant​

Creates a render variant. A design references it by id in renderVariantIds, and resolution returns the full variant records.

POST /api/credential-design/v1/designs/render/variants

The full request and response schema is in the API reference, or open the API reference tab to read it inline.

List render variants​

Lists the render variants in the tenant. Get, update, and delete a single variant by id at /designs/render/variants/{variantId} (credential-design.render-variants.get / .update / .delete).

GET /api/credential-design/v1/designs/render/variants

The full request and response schema is in the API reference, or open the API reference tab to read it inline.

Source snapshots​

When a design is imported, the raw fetched payload is stored as a source snapshot, retained so the design can be refreshed and audited. A snapshot carries the source type and URL, the ETag and integrity digest used for conditional refresh, and a reference to the stored bytes.

Get a source snapshot​

Returns the metadata and stored payload reference for one snapshot.

GET /api/credential-design/v1/designs/snapshots/{snapshotId}

The full request and response schema is in the API reference, or open the API reference tab to read it inline.

Refresh a source snapshot​

Re-fetches the snapshot's source, using its stored ETag for a conditional request, and returns the updated snapshot.

POST /api/credential-design/v1/designs/snapshots/{snapshotId}/refresh

The full request and response schema is in the API reference, or open the API reference tab to read it inline.

Design assets​

Branding assets (logo, background image, SVG template, PDF template) are stored and served as raw bytes, addressed by design id, locale, and asset type. {locale} is a BCP-47 tag (en, nl, en-GB); {assetType} is one of LOGO, BACKGROUND_IMAGE, SVG_TEMPLATE, or PDF_TEMPLATE. Upload sends the bytes with the asset's MIME type in the request Content-Type header and returns an AssetReference; download returns the bytes with the stored Content-Type.

Upload a design asset​

Uploads a branding asset as application/octet-stream. The design id, locale, and asset type come from the path; the content type comes from the request header. Returns a reference to the stored asset.

POST /api/credential-design/v1/designs/credentials/{designId}/assets/{locale}/{assetType}

The full request and response schema is in the API reference, or open the API reference tab to read it inline.

Download a design asset​

Downloads a stored asset as raw bytes, with the Content-Type it was stored as (for example image/png, image/svg+xml, or application/pdf).

GET /api/credential-design/v1/designs/credentials/{designId}/assets/{locale}/{assetType}

The full request and response schema is in the API reference, or open the API reference tab to read it inline.

The wire shape of every request and response, including all model fields and their types, is in the Credential Design API reference.