Changelog

All notable changes to the DeepCredentials B2B API.

• Credential Invitations API — Service users can create, list, get, rotate, and revoke invitations under /b2b/v1/credential-invitations. Create and rotate return the one-time plaintext code; list, get, and revoke expose code-free metadata.
• credential_invitation.status_changed webhook — An opt-in terminal event for invitation redeemed, expired, and revoked transitions. The slim payload contains invitation_id, status, and offer_id only after redemption. Existing webhook configurations must enable the event in the portal.

• Partner-owned invitation delivery — DeepCredentials does not email codes created or rotated through the B2B invitation API. The partner owns how it delivers the code and presents the redemption experience; its backend can exchange the recipient's email and code through the public redemption endpoint.
• Progress callbacks clarified — Verification, invitation, and issuance webhooks are slim hints followed by authenticated B2B GET reconciliation. Webhook delivery currently makes one synchronous attempt and can be missed.
• reference_id clarified — The field is optional correlation metadata only; it does not provide idempotency, uniqueness, or response caching.

• template_id → credential_definition_id — B2B request bodies and query parameters that previously accepted template_id now require credential_definition_id. Applies to POST /b2b/v1/verification-sessions, POST /b2b/v1/credential-offers, and the list query filters on those resources.
• template → credential_definition in responses — The top-level response object previously named template is now named credential_definition. Inner fields (id, vct, name, has_logo) are unchanged. Terminology throughout the API is now "Credential Definition" rather than "Template".

• GET /b2b/v1/credential-definitions — Returns the credential definitions available to your organization. Any authenticated service user can call this endpoint (no additional scope required beyond a valid token with X-Org-Id and X-Environment).

• "Open in API reference" deep-links — Every code sample in the guides now has an immediate deep-link to the matching operation in the rendered API reference.
• Broadened intro — The home page and Quickstart now cover all three API pillars: verification, issuance, and self-service.

• Portal-issued credentials retired. API keys and OAuth clients minted in the DeepCredentials portal no longer work. Authentication now uses DeepAdmin service users authenticated against the DeepCloud SSO realm with the OAuth 2.0 Resource Owner Password Credentials grant. See the new Service Users guide.
• POST /b2b/v1/oauth/token removed. Exchange credentials directly with POST <keycloak-realm>/protocol/openid-connect/token against deepcloud.swiss (prod) or int.deepcloud.swiss (test).
• X-Org-Id and X-Environment headers are now required on every /b2b/v1/* request. X-Org-Id is the UUID of the organization the service user is a member of; X-Environment is beta or production.
• X-Api-Key header is no longer accepted. Authenticate exclusively with Authorization: Bearer <access_token> from the DeepCloud SSO token endpoint.

• API Keys and OAuth Clients management surfaces in the DeepCredentials portal.
• Authentication API OpenAPI spec (the /b2b/v1/oauth/token operation is gone).

• Scope strings renamed — B2B scopes are now namespaced under deepcredentials.*:

  • issuance → deepcredentials.issue
  • verification → deepcredentials.verify
  • self_service → deepcredentials.self-service

  Provision new credentials with the namespaced names. Enforcement will roll out together with the matching DeepAdmin update; until then, in-flight tokens carrying the legacy names continue to work.

• identification_filled claim source — Self-service configs can now mark a template claim as automatically pre-filled from the identification provider's verified attributes. Tenants configure the per-claim mapping in the portal (no B2B API surface). The webhook decision flow benefits passively: by the time self_service.request.submitted fires, the snapshot's claims field already reflects the merged result (user → identification → admin), so an empty admin_claims approve issues a credential carrying the identification-derived values.
• editable_field_sources enum extended — GET /b2b/v1/self-service/requests/{id} may now return "identification_filled" alongside "user_filled" and "admin_filled". See the Self-Service Flow guide.

• Credential validity — Credentials are now issued with a tenant-controlled exp claim. Set a default on the credential template (portal → Templates) and override per-issuance via the new optional validity_seconds field on POST /b2b/v1/credential-offers. Send no value to inherit the template default; the credential is issued without an exp claim (never expires) only when both the template default and request override are absent. Self-service configs always carry their own explicit validity (or explicit "never expires") chosen at config creation. Allowed range: 60 seconds to 10 years. Issued-credential responses (GET /b2b/v1/issued-credentials/{id}, list, and webhook payload-fetch) now include valid_from and valid_until so you can show expiry in your UI and react before a credential lapses.
• Self-service request snapshot — full claim schema — GET /b2b/v1/self-service/requests/{requestId} now returns editable_fields / editable_field_types / editable_field_sources describing every claim on the template (not just admin-filled ones). Enables rendering a "review & override" form without a second template fetch. See the Self-Service Flow guide.

• Issued credential status semantics — The status field (active / suspended / revoked) is the revocation lifecycle (driven by the status list). Expiration is now expressed separately via valid_until. A credential can be active and past its valid_until simultaneously — wallets and verifiers reject it on the exp claim; we don't automatically flip its status.
• admin_claims may override user-supplied claims — POST /b2b/v1/self-service/requests/{requestId}/decision already accepted any template claim key in the admin_claims payload; the contract is now explicit: when a key appears in both the user submission and your admin_claims, your value wins and is the one stamped on the credential. admin_filled_* continues to describe the required contract only.

• Self-Service API — GET /b2b/v1/self-service/requests/{requestId} returns the full request snapshot (status, captured claims, identification result, offer id, timestamps, plus the admin-claims schema — admin_filled_fields / admin_filled_types / admin_filled_required, mirroring how verification ships requested_fields + credential_subject_types so the tenant can dynamically render or validate admin_claims without hard-coded template knowledge). POST /b2b/v1/self-service/requests/{requestId}/decision approves or rejects an end-user-initiated request — required for tenants whose configs run in webhook verification mode.
• Self-service webhook events — Six events covering the full lifecycle:
  • self_service.request.submitted — fires for webhook-mode configs when a request is ready for a decision.
  • self_service.request.approved / self_service.request.rejected — fire for all verification modes so you have an audit trail of every decision.
  • self_service.request.credential_issued — terminal success; the wallet accepted the credential.
  • self_service.request.offer_expired / self_service.request.failed — terminal post-approval failure paths (offer TTL exceeded, wallet rejected).
• self_service scope — Required for the Self-Service API and selectable on API keys / OAuth clients in the portal.
• Self-Service Flow guide — End-to-end walkthrough of the three verification modes (manual, webhook, automatic), lifecycle diagram, full user ↔ Portal ↔ tenant-backend sequence, and webhook payload contract.
• Webhook subscription management — The portal webhook page now has a per-event checkbox grid grouped by family (Verification / Credential Issuance / Self-Service). Unchecked events are silently dropped at our edge — no delivery, no retry. New webhook configs default to all events on; existing configs keep their current set and have to explicitly opt in to events added in future releases.

• Scopes documentation — The scopes table previously listed credentials.read / credentials.write, which never existed. Replaced with the actual scopes: verification, issuance, self_service.

• Verification API — Create and poll OID4VP verification sessions (POST and GET /b2b/v1/verification-sessions).
• Authentication API — OAuth 2.0 Client Credentials token exchange (POST /b2b/v1/oauth/token).
• Health API — Credential validation and connectivity check (GET /b2b/v1/health).
• Webhook Events API — OpenAPI 3.1 webhook spec for verification.completed with full event schema and signature headers.
• Webhooks guide — Setup, HMAC-SHA256 signature verification, and secret rotation.
• Authentication methods — API keys and OAuth 2.0.