Issue a credential

Overview

Once you’ve picked a preset (see Browse credential presets), issue against it by passing the preset id along with the user’s data. This guide uses didx:basic-identity, an sd-jwt credential with attributes firstName and lastName.

Need a custom shape that no preset matches? See Custom credential template. For everything else, use a preset.

Endpoint

POST https://test.didxtech.com/me-creds/api/v1/issuances

Request

curl -X POST "https://test.didxtech.com/me-creds/api/v1/issuances" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "credentials": [
      {
        "presetId": "didx:basic-identity",
        "attributes": {
          "firstName": "John",
          "lastName": "Doe"
        }
      }
    ]
  }'

Request body

The body has a single top-level field, credentials, which is an array. Each entry describes one credential to issue as part of this issuance. The most common case is a single-entry array; pass more than one to bundle multiple credentials into the same offer.

Field	Type	Description
`credentials`	array	At least one credential to issue. Order is preserved.
`credentials[].presetId`	string	The id of the preset you’re issuing against (e.g. `didx:basic-identity`). Browse available presets via the `/presets/credentials` family of listings (see Browse credential presets).
`credentials[].attributes`	object	Key-value pairs for the user’s data. The keys must exactly match the attributes declared by the preset; both missing required attributes and undeclared keys are rejected with a 400.

For each entry, pass either presetId or credentialTemplateId, not both. Most integrations only ever use presetId. The template path is for custom credential shapes.

Response

HTTP 201 Created What you get back is an issuance resource. The issuance represents the offer interaction itself — the protocol for getting credentials into the user’s wallet — and it carries the credential resources it produces inside credentials[]. The next page, Issuance vs credential, goes into the resource split in detail. For now, the short version is: the top-level id belongs to the offer flow, and each credentials[].id is a credential you’ll act on later.

{
  "data": {
    "id": "cm7d9cq5600pwk3zq3kmpg8uc",
    "status": "offered",
    "error": null,
    "credentials": [
      {
        "id": "cm7d9cq5600pzk3zq9wzxxtc3",
        "status": "offered",
        "credentialTemplateId": "cm2ytsdid009u4ke3t30aiuvc",
        "exchange": "openid4vc",
        "format": "sd-jwt-vc",
        "revocable": true
      }
    ],
    "offerUri": "https://test.didxtech.com/invitation?credential_offer_uri=...",
    "offerQrUri": "https://test.didxtech.com/invitation?credential_offer_uri=...&qr=true",
    "createdAt": "2025-02-20T11:27:37.051Z",
    "updatedAt": "2025-02-20T11:27:37.051Z"
  }
}

Key response fields

Field	Description
`id`	The issuance id (offer session). Use this to look up offer state later.
`status`	Issuance status: `offered` once the offer is ready to be claimed. Transitions to `completed`, `failed`, or `expired`.
`offerUri`	Direct link the user can paste into their wallet to accept the credential
`offerQrUri`	QR-optimised version of the offer URI for wallet scanning
`credentials[]`	The credentials this issuance produces, one entry each.
`credentials[].id`	The credential id. Use this for revocation and credential-resource lookups.
`credentials[].status`	Credential status: `offered` → `issued` (or `revoked` later).
`credentials[].format`	`sd-jwt-vc` (selective disclosure) or `mso_mdoc`.
`credentials[].revocable`	Whether this credential supports revocation (SD-JWT yes, mDoc no today).

The top-level id and the inner credentials[].id are different resources with different endpoints. Capture both now — recovering them later is more work. See the next section, Issuance vs credential.

Deliver the offer

Get the credential offer to the user. Two options:

By email, username, or other identifier: Deliver via identifier.
As a QR code or deeplink rendered in your own UI: Deliver out of band.

Overview

User Onboarding

Issuance

Verification

Webhooks

Custom Templates (advanced)

Errors

Overview

Endpoint

Request

Request body

Response

Key response fields

Deliver the offer

​Overview

​Endpoint

​Request

​Request body

​Response

​Key response fields

​Deliver the offer

Overview

Endpoint

Request

Request body

Response

Key response fields

Deliver the offer