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.

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.

Email is never collected as a form field. ~3 seconds after the request enters awaiting_verification, the SPA's waiting screen reveals an inline 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 3-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 your approve webhook is delivered immediately.

If the user closes the page without opting in (or your decision arrives before the 3-second delay), request.email stays NULL. 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 six self-service webhooks (submitted, approved, rejected, credential_issued, offer_expired, failed) 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 API credential 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 verification ships requested_fields + credential_subject_types, 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"]
}

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

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_required 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, with the deepcredentials.self-service scope. There is no B2B API-key authentication path. You have 7 days (the invitation TTL) after the submitted event before the request expires.

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_required from the GET snapshot to know which keys you must supply. DeepCredentials merges your admin_claims with the user-filled claims captured in the submission, validates the whole set against the credential definition schema, then creates the credential invitation and emails the end-user.

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 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 shown to the end-user verbatim in the rejection email and on the status page.

The decision endpoint is single-shot — a second call with the same requestId returns 400 failed_precondition with the current state. If your backend retries on transport failure, treat a failed_precondition response as confirmation the request was already 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.