Credential Issuance Flow

This guide explains both B2B issuance branches: an immediate credential offer and a partner-delivered invitation code. Both branches end in the same credential-offer and issued-credential lifecycle.

• An API credential with the deepcredentials.issue scope. See Authentication.
• A credential definition configured for your organization in the portal.
• Issuer setup completed (DID + status list) in the portal.
• For webhook progress notifications, a destination and event subscriptions configured in Settings > Webhooks in the portal.

Portal configuration comes first. At runtime, your partner integration uses the B2B endpoints below; invitation redemption is the one anonymous public step performed for the recipient.

If issuance follows an eID check, wait for status: success and evaluate credential_status through the Verification Flow, then fetch the disclosed values with authenticated GET. Your system decides how to build the new credential claims: it may copy, transform, supplement, or ignore the verified values. Issuance does not accept a verification-session ID and does not require the new claims to match the eID.

Use the immediate branch when the holder can consume the offer now. Use an invitation when the holder should redeem later or through a separate channel controlled by your system.

Once issued, a credential has its own lifecycle:

These three values cover the revocation lifecycle (status-list driven). Expiration is an orthogonal axis — see Credential validity below.

Every credential carries an SD-JWT exp claim (when set) that wallets and verifiers honour independently of status. The lifetime is resolved at issuance time from this fallback chain:

1. validity_seconds on the create request — explicit override, only for this offer.
2. default_validity_seconds on the credential definition — tenant-set default for this vct.
3. No exp claim — credential never expires (only reached if both above are absent).

The value is stamped onto the SD-JWT at signing time. The resolved lifetime is echoed back on the offer response as credential_validity_seconds; once the credential is issued it surfaces as valid_until (alongside valid_from, which mirrors iat/nbf) on the issued-credential response — GET /b2b/v1/issued-credentials/{id}. These surfaces are read-only — credentials are immutably signed, so once issued the validity window cannot be changed without re-issuing.

Range: 60 seconds to 10 years (315 360 000 seconds). Self-service flows always carry their own explicit validity chosen on the config; the request-level override here is for direct B2B issuance only.

An invitation stores the credential claims and eventual offer settings until the recipient redeems a one-time code. B2B list, get, and revoke responses never expose the code or claims. Only successful create and rotate responses contain the plaintext code.

Open in API reference →

curl -i -X POST \
  https://api.dev.deepcredentials.swiss/b2b/v1/credential-invitations \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'X-Environment: beta' \
  -H 'X-Org-Id: 497f6eca-6276-4993-bfeb-53cbbbba6f08' \
  -d '{
    "credential_definition_id": "db167a9d-8182-430c-bff0-f9baa6d48bb6",
    "email": "alice@example.com",
    "claims": {
      "given_name": "Alice",
      "employee_number": "E-1042"
    },
    "reference_id": "partner-invitation-1042",
    "invitation_ttl_seconds": 86400,
    "offer_validity_seconds": 600,
    "validity_seconds": 31536000
  }'

reference_id is optional correlation metadata echoed on the invitation. It is not an idempotency key, uniqueness constraint, or cached-response key. Repeating create can create another resource unless the pending-recipient uniqueness rule rejects it.

The successful response includes code, formatted like 7KMTD-5X7Q9. Send that secret through your own email, SMS, or other channel. DeepCredentials does not send the email and does not return a redemption_url for this B2B operation.

Keep the submitted claims and validity_seconds in your own durable request record. Invitation create, list, and get responses intentionally omit both, so they cannot be reconstructed from the B2B resource later.

Your system decides where and how to present the redemption experience. Once it has the recipient's email address and one-time code, its backend exchanges them through the anonymous public endpoint:

POST /api/v1/public/credential-invitations/redeem
Content-Type: application/json

{
  "email": "alice@example.com",
  "code": "7KMTD-5X7Q9"
}

The response contains a fresh OID4VCI deeplink, qr_content_base64, offer_id, and expires_at. Your system decides how to deliver or display those values to the recipient. This endpoint requires no service-user token; do not expose a B2B token to the recipient or include one in the redemption call.

A successful redemption atomically marks the invitation redeemed and creates a fresh OID4VCI offer. The credential_invitation.status_changed webhook contains the resulting offer_id; from that point, track the offer through GET /b2b/v1/credential-offers/{offerId} and issuing.status_changed.

List results are scoped by your X-Org-Id and X-Environment, ordered newest first, and contain no plaintext code or claims. The optional filters are exact matches.

curl -i -X GET \
  'https://api.dev.deepcredentials.swiss/b2b/v1/credential-invitations?limit=50&offset=0&status=pending&credential_definition_id=497f6eca-6276-4993-bfeb-53cbbbba6f08&email=string&reference_id=string' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'X-Environment: beta' \
  -H 'X-Org-Id: 497f6eca-6276-4993-bfeb-53cbbbba6f08'

Use get when you already have the invitation ID:

curl -i -X GET \
  'https://api.dev.deepcredentials.swiss/b2b/v1/credential-invitations/{invitationId}' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'X-Environment: beta' \
  -H 'X-Org-Id: 497f6eca-6276-4993-bfeb-53cbbbba6f08'

Because create is not idempotent, do not blindly retry after an ambiguous transport failure. Persist the complete create request locally and use a distinct reference_id for each intended invitation:

1. List with the exact credential_definition_id, normalized email, and your reference_id; do not restrict the first lookup to pending, because the invitation may have reached a terminal state while the response was unavailable.
2. If there is exactly one match, compare all returned metadata with your durable request record. Reconcile a terminal match through its status and redeemed_offer_id rather than creating another invitation.
3. Rotate only when the matching invitation is still pending and your system can establish that it belongs to this create attempt, then deliver only the replacement code returned by rotate.
4. If there is no match, retry create. If that returns already_exists, list by pending status, definition, and email without reference_id and resolve the conflicting resource manually.
5. If there is more than one match or the identity is otherwise ambiguous, do not select, rotate, or revoke a resource automatically.

The pending-recipient uniqueness rule prevents two pending invitations for the same organization, environment, credential definition, and normalized email. That rule supports discovery but does not turn reference_id into an idempotency key. List/get responses do not expose claims or validity_seconds, so those hidden inputs can be verified only against the request record retained by your system.

curl -i -X POST \
  'https://api.dev.deepcredentials.swiss/b2b/v1/credential-invitations/{invitationId}/rotate-code' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'X-Environment: beta' \
  -H 'X-Org-Id: 497f6eca-6276-4993-bfeb-53cbbbba6f08' \
  -d '{
    "invitation_ttl_seconds": 86400
  }'

Rotation is deliberately non-idempotent. Every successful call generates a new code, invalidates the previous one, resets failed attempts, and replaces the expiry. If the response is lost, call rotate again until you receive a response; then use only that response's code. DeepCredentials never emails a B2B replacement code.

curl -i -X POST \
  'https://api.dev.deepcredentials.swiss/b2b/v1/credential-invitations/{invitationId}/revoke' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'X-Environment: beta' \
  -H 'X-Org-Id: 497f6eca-6276-4993-bfeb-53cbbbba6f08'

Only a pending invitation can be revoked. Repeating revoke, or revoking an invitation that is already redeemed or expired, returns failed_precondition.

Open in API reference →

curl -i -X POST \
  https://api.dev.deepcredentials.swiss/b2b/v1/credential-offers \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'X-Environment: beta' \
  -H 'X-Org-Id: 497f6eca-6276-4993-bfeb-53cbbbba6f08' \
  -d '{
    "credential_definition_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "claims": {
      "given_name": "Max",
      "family_name": "Mustermann",
      "date_of_birth": "1990-01-15",
      "is_over_18": true
    },
    "reference_id": "order-12345",
    "offer_validity_seconds": 600
  }'

validity_seconds is optional — omit to inherit the credential definition's default_validity_seconds. See Credential validity for the full fallback chain.

The response includes a QR code and deeplink for the wallet holder.

You have two options to present the issuance offer to the wallet holder:

The qr_content_base64 field is a standard Base64-encoded PNG image. Display it directly:

<img src="data:image/png;base64,iVBORw0KGgo..." alt="Scan to receive your credential" />

The deeplink field contains a URI that opens the wallet app directly:

openid-credential-offer://?credential_offer=...

Use this when the user is on a mobile device — redirect them to the deeplink instead of showing a QR code.

Poll GET /b2b/v1/credential-offers/{offerId} until the status is no longer pending:

Open in API reference →

curl -i -X GET \
  'https://api.dev.deepcredentials.swiss/b2b/v1/credential-offers/{offerId}' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'X-Environment: beta' \
  -H 'X-Org-Id: 497f6eca-6276-4993-bfeb-53cbbbba6f08'

While status is pending, deeplink and qr_content_base64 are present. When status changes to issued, the issued_credential_id field contains the credential ID and deeplink/qr_content_base64 are omitted.

Polling recommendations:

• Poll every 2–3 seconds.
• Stop when status is issued, failed, or expired.
• Respect the expires_at timestamp — stop polling after expiration.

Subscribe to the issuing.status_changed webhook event to receive a slim terminal-state hint (offer_id and status). Follow every callback with authenticated GET /b2b/v1/credential-offers/{offerId} when you need the authoritative offer snapshot. The webhook does not contain the offer claims or duplicate the GET response.

For the delayed branch, also opt in to credential_invitation.status_changed. It fires only for redeemed, expired, or revoked. A redeemed callback contains offer_id, which is the handoff to the normal offer lifecycle; expired and revoked callbacks omit it.

See the Webhooks guide for setup, signature verification, and secret rotation.

Use GET /b2b/v1/issued-credentials/{credentialId} to retrieve details about an issued credential, including its current status.

To confirm that a holder actually has the credential in their wallet, use the Verification API to request a presentation of the recently issued credential:

1. Issue the credential via POST /b2b/v1/credential-offers.
2. Wait for issued status (poll or webhook).
3. Create a verification session via POST /b2b/v1/verification-sessions using the same credential definition.
4. Ask the holder to present the credential by scanning the verification QR code.
5. On success — the credential is confirmed to be in the holder's wallet and valid.

This "issue-then-verify" pattern gives you cryptographic proof that the holder possesses the credential, which issued status alone cannot guarantee.

On failure: the offer status changes to failed. Create a new offer to retry.

On expiration: offers that remain pending past their expires_at transition to expired automatically. Default TTL is 10 minutes.

See Error Handling for a complete list of error codes.

• Webhooks — Receive issuance results in real time.
• Verification Flow — Verify credentials from wallet holders.
• Error Handling — Handle all possible error scenarios.