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.

If no preset matches the shape you need, see Custom credential template. For everything else, use a preset.

Endpoint

POST $BASE_URL/me-creds/api/v1/issuances

Request

curl -X POST "$BASE_URL/me-creds/api/v1/issuances" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "credentials": [
      {
        "reference": "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[].reference`	string	What to issue, as `KIND:VALUE`. See the reference kinds below.
`credentials[].attributes`	object	Key-value pairs for the user’s data. The keys must exactly match the attributes the preset declares; missing required attributes and undeclared keys both return a 400.

Reference kinds

reference is an opaque selector the platform resolves to the template it issues from. It splits on the first colon only, so the value may itself contain colons, as preset ids and credential types both do.

Kind	Example	Resolves to
`presetId`	`presetId:didx:basic-identity`	The preset, then through it to your managed template. The usual choice.
`credentialType`	`credentialType:urn:eu.europa.ec.eudi:pid:1`	The preset that defines that credential type (SD-JWT `vct` or mDoc DocType).
`templateId`	`templateId:cm2ytsdid009u4ke3t30aiuvc`	That template directly. For custom shapes.

The platform rejects unknown kinds rather than guessing. A ~ prefix marks a private preset. It’s part of the id, so pass it verbatim: presetId:~acme:internal-badge.

The older top-level presetId and credentialTemplateId fields still work but are deprecated. Pass exactly one of reference, presetId, or credentialTemplateId per entry. Supplying more than one returns a 400. New integrations should use reference.

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 that 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://creds-app.test.didxtech.com/invitation?credential_offer_uri=...",
    "offerQrUri": "https://creds-app.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 user can claim the offer. 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`, then `issued`, and possibly `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, because recovering them later is more work. See the next section, Issuance vs credential.

Deliver the offer

Get the credential offer to the user. There are 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

Branding

Webhooks

Custom Templates (advanced)

Errors

Overview

Endpoint

Request

Request body

Reference kinds

Response

Key response fields

Deliver the offer

​Overview

​Endpoint

​Request

​Request body

​Reference kinds

​Response

​Key response fields

​Deliver the offer

Overview

Endpoint

Request

Request body

Reference kinds

Response

Key response fields

Deliver the offer