Self-Service — Detailed Reference

Read this when you need the full state machine, every webhook payload, idempotency semantics, or error codes. For a first integration walk through Quickstart instead; for a concrete end-to-end example see Walkthrough — City Card.

For machine-to-machine issuance where your backend already has all the data, use Credential Offers instead — self-service is the share-link flow where the end-user (or an identification provider) supplies the data.

Each config picks one of three modes — the mode decides who approves a submission.

This guide focuses on the webhook mode — it's the one that touches the B2B API. manual and automatic configs use the same lifecycle but skip the webhook round-trip with your backend.

Any state before issued also moves to expired when the request's 7-day window lapses, counted from when the request was created (the self-declaration submit, or the start of identification).

This sequence covers the full path: end-user clicks the share-link, optionally verifies through identification, submits, your backend approves, end-user picks up the credential.

The rejected path swaps the decision payload for {"decision": "reject", "reason": "..."} and the subsequent webhook becomes self_service.request.rejected. No invitation is created. The rejection email is sent only if the user opted into delivery; without opt-in we still publish the webhook for the tenant's audit trail and skip the mail.

If the wallet never finishes the OID4VCI exchange (offer TTL exceeded, wallet rejected the credential) DeepCredentials fires self_service.request.offer_expired or self_service.request.failed instead of credential_issued. offer_expired is also sent when a request's 7-day window lapses before an offer was created. A failed identification sends no webhook. If the organization revokes the invitation or offer before the wallet accepts it, the request moves to revoked and DeepCredentials fires self_service.request.revoked.

Email is never collected as a form field. How the address is collected depends on the config's Credential delivery setting:

• QR only — no email is asked for. On approve the live credential offer is created directly.
• Email only — the SPA asks for the address right after submission. The request waits in awaiting_email, and the submitted webhook fires only once the address is set. On approve the end-user always gets a redemption email.
• Let the user choose — ~10 seconds after the request enters awaiting_verification, the SPA's waiting screen reveals an inline opt-in panel, described below.

In the opt-in panel:

• Self-declaration only: empty input, user types if they want updates.
• Identification: input is pre-filled (read-only) with the address the identification provider returned — but the user still has to click the button to authorise delivery. We never email an address the user didn't actively confirm.

The ~10-second buffer lets fast tenant decisions resolve before we ask: if your /decision call lands while the user is still on the waiting page, the panel never appears and the credential is delivered by QR.

If the user closes the page without opting in (or your decision arrives before the panel appears), email stays unset on the snapshot. On approve we then create the live credential offer directly and the SPA picks it up via status polling — no redemption email, but the credential still ships. On reject we publish the webhook and skip the rejection email.

All seven self-service webhooks (submitted, approved, rejected, credential_issued, offer_expired, failed, revoked) share the slim envelope:

{
  "event": "self_service.request.submitted",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2026-05-16T10:00:00Z",
  "data": {
    "request_id": "8a3b1f2e-9c4d-4e5a-b1c2-d3e4f5a6b7c8"
  }
}

The data field carries only request_id — no captured claims, email, or identification data are sent over the webhook channel. After receiving any of these events, call GET /b2b/v1/self-service/requests/{requestId} with your service-user access token to fetch the full snapshot.

The GET /b2b/v1/self-service/requests/{requestId} response carries three fields that describe the claims the tenant is expected to fill — mirrors how a verification session ships requested_attributes with a value_type each, so you can render a form or validate input dynamically instead of hard-coding what each config wants:

Example fragment:

{
  "admin_filled_fields": ["employee_id", "department", "office_number"],
  "admin_filled_types": {
    "employee_id": "string",
    "department": "string",
    "office_number": "integer"
  },
  "admin_filled_required": ["employee_id", "department"]
}

On approve, your admin_claims must contain every key in admin_filled_fields — optional ones included — each with a valid value; a missing key is refused with 400 invalid_argument (admin_claims is missing required key "…").

If the config has no admin-filled claims, all three are empty ([], {}, []) and you can approve without admin_claims.

admin_filled_* describes only the contract: which keys the admin is expected to supply (and which are mandatory). It is not a whitelist — the decision endpoint accepts any credential definition claim in your admin_claims payload, including keys the end-user already filled in (and keys pre-populated from an identification flow). When a key appears in more than one source, the layering is fixed: user → identification → admin, with later layers winning.

To make this discoverable without a separate credential definition fetch, the snapshot also carries the full credential definition claim set:

Typical usage: render a "review & override" form with one input per editable_fields entry. Pre-fill from the snapshot's claims field — it already carries the merged result of user submission + identification mapping, so the same input shows whatever value would be stamped on the credential today. Submit only the keys the admin actually changed plus every admin_filled_fields key.

The self_service.request.submitted webhook carries only request_id — no captured data. To decide, your backend goes through two calls:

1. Fetch the snapshot via GET /b2b/v1/self-service/requests/{requestId}. The response returns the captured user claims, extra fields, identification result (if any), and the admin_filled_* schema you need to assemble admin_claims.
2. POST your decision to /b2b/v1/self-service/requests/{requestId}/decision.

Both calls use a Bearer token obtained for a DeepAdmin service user through DeepCloud; request the deepcredentials.self-service scope for it (see Service Users → Scopes). There is no B2B API-key authentication path. A request expires 7 days after it was created (the self-declaration submit, or the start of identification); decide within that window, as an expired request can no longer be decided.

Open in API reference →

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

The response shape — including the admin_filled_* schema described above — is documented under the Self-Service API reference.

Open in API reference →

curl -i -X POST \
  'https://api.dev.deepcredentials.swiss/b2b/v1/self-service/requests/{requestId}/decision' \
  -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 '{
    "decision": "approve",
    "admin_claims": {
      "is_employee": true
    }
  }'

admin_claims is required when the config has any claim keys marked admin-filled. Use admin_filled_fields from the GET snapshot to know which keys you must supply. DeepCredentials merges your admin_claims with the user-filled and identification-mapped claims, validates the whole set against the credential definition schema, then — depending on delivery — creates a credential invitation and emails the end-user the redemption link (response status: "invitation_sent"), or creates the live credential offer directly (status: "issued" with offer_id).

admin_claims may also include keys the end-user already filled in — your value overrides theirs (see Overriding user-supplied claims above). Keys absent from admin_claims flow through from the user submission and the identification mapping unchanged.

Open in API reference →

curl -i -X POST \
  'https://api.dev.deepcredentials.swiss/b2b/v1/self-service/requests/{requestId}/decision' \
  -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 '{
    "decision": "approve",
    "admin_claims": {
      "is_employee": true
    }
  }'

reason is required on reject (up to 1000 characters) and is shown to the end-user verbatim on the status page, and in the rejection email if they opted into email delivery.

The decision endpoint is single-shot — a second call with the same requestId returns 400 failed_precondition, with the current status in the message. If your backend retries on transport failure, treat a failed_precondition response as a cue to re-fetch the snapshot: its status tells you whether (and how) the request was decided.

See the Error Handling guide for the full taxonomy.

• Quickstart — the four-step integration path.
• Walkthrough — City Card — a concrete end-to-end example.
• Self-Service API reference — GET + POST /decision schemas.
• Webhook Events — full payload schemas for self_service.request.*.
• Webhooks guide — event delivery, signature verification, secret rotation.
• Credential Issuance Flow — machine-to-machine alternative when your backend has all the data up front.