Essence Authentication Service API
API for user authentication, registration, and session management. ## Features - User registration with email/password - Multi-factor authentication (TOTP, SMS, Email) - Device fingerprinting and trust management - JWT tokens with RS256 signing - Refresh token rotation - Federated identity (UAE PASS, Azure AD, Okta, etc.) ## Security - Zero-knowledge architecture (client-side password hashing) - Account lockout policy (5 attempts = 30min) - Token blacklisting for revocation - Constant-time password verification (SEC-005) - Adopted Essence platform foundation (Phase 1 WS-B)
Generated from the Auth service's code at build time (api-specs/generated/Auth/Essence.Identity.Auth.Api.json) and drift-checked in CI. It describes what the code registers, which is not the same as what any one deployment has routed.
AccessRecertificationTermination
/api/v1/access-recertification/terminationsTerminates a named staff principal's sessions and issued credentials under the authority of a recertification campaign.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
TerminatePrincipalAccessRequestasapplication/*+json,application/json,text/json
Responses
TerminatePrincipalAccessResultProblemDetailsProblemDetailsProblemDetailsTerminatePrincipalAccessResultAccountAction
/api/v1/account/action-noticeReturns the honest account-action notice for the signed-in / affected account. When a `case` reference is supplied it scopes the lookup to that decision. Returns 204 when there is no action on the account.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
case | query | string | no | — |
Request body
No request body.
Responses
AccountActionNoticeDto/api/v1/account/action-notice/by-tokenReturns the account-action notice for the holder of a single-purpose notice token, WITHOUT a session. A suspended account cannot hold a session, so the person the notice is about would otherwise be the one person unable to read it — including the appeal route it describes. The token is minted only when that person successfully proves their password at sign-in, is 256 bits of CSPRNG output, is stored only as a hash, expires in 30 minutes, and is accepted by this endpoint alone. It is deliberately not a bearer token: it can authenticate nothing else. The appeal case reference is NOT usable for this purpose — it carries ~32 bits behind a guessable date prefix and does not exist until an appeal has already been opened.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
token | query | string | no | — |
Request body
No request body.
Responses
AccountActionNoticeDtoProblemDetails/api/v1/account/actionsApplies a graduated administrative action to an end-user account (the EPIC 48 moderation decision). Admin-only. Emits the shared account-action event.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
ApplyAccountActionRequestasapplication/*+json,application/json,text/json
Responses
ApplyAccountActionResultProblemDetailsProblemDetails/api/v1/account/appealsSubmits an appeal against an account action on behalf of the affected user. Returns a returnable case reference + the response-SLA window.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
SubmitAppealRequestasapplication/*+json,application/json,text/json
Responses
AppealCaseDtoProblemDetailsProblemDetails/api/v1/account/appeals/by-tokenRe-reads the appeal opened against the token's action, WITHOUT a session, so a suspended holder can return and track it.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
token | query | string | no | — |
Request body
No request body.
Responses
AppealCaseDtoProblemDetails/api/v1/account/appeals/by-tokenSubmits an appeal using the single-purpose notice token, WITHOUT a session — the only route available to a suspended holder. The notice this token was minted for tells its holder they may appeal. The session-based `POST appeals` above resolves the appellant from JWT claims, so until this existed the right to appeal was announced to exactly the people who could not exercise it. The appealed decision is resolved FROM the token — it is not accepted in the body — so the token can only ever open an appeal against its own action.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
SubmitAppealByTokenRequestasapplication/*+json,application/json,text/json
Responses
AppealCaseDtoProblemDetailsProblemDetails/api/v1/account/appeals/{caseRef}Re-fetches an appeal's status by case reference.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
caseRef | path | string | yes | — |
Request body
No request body.
Responses
AppealCaseDtoProblemDetailsAccountClosureCancel
/api/v1/auth/account/closure/cancelCancel the closure the link was minted for, and reopen the account.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
AccountClosureCancelRequestasapplication/*+json,application/json,text/json
Responses
AccountClosureCancelResponseProblemDetailsAccountClosureDecisions
/api/v1/auth/account-closure-decisions/fraudDecide a fraud closure (T7). Closes nothing until a different principal approves it.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
DecideFraudClosureRequestasapplication/*+json,application/json,text/json
Responses
AccountClosureDecisionResultProblemDetailsProblemDetails/api/v1/auth/account-closure-decisions/{id}Read one closure decision.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | — |
Request body
No request body.
Responses
AccountClosureDecisionResultProblemDetails/api/v1/auth/account-closure-decisions/{id}/approveApprove a decided fraud closure or a verified death — by a different principal. Closes the account.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | — |
Request body
No request body.
Responses
AccountClosureDecisionResultProblemDetailsProblemDetailsProblemDetails/api/v1/auth/account-closure-decisions/{id}/rejectStop an open closure. Nothing is closed.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | — |
Request body
No request body.
Responses
AccountClosureDecisionResultProblemDetailsProblemDetailsProblemDetails/api/v1/auth/account-closure-decisions/{id}/verify-deathVerify a reported death (T8, the Support lead). A different principal must approve it.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | — |
Request body
No request body.
Responses
AccountClosureDecisionResultProblemDetailsProblemDetailsProblemDetailsAccountFactorHolds
/api/v1/auth/account-factor-holds/currentThe hold in force on the caller's text-message factor, if any.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
No request body.
Responses
AccountFactorHoldView/api/v1/auth/account-factor-holds/{holdId}/confirmEnds the hold: the caller confirms the number change was theirs.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
holdId | path | string (uuid) | yes | — |
Request body
No request body.
Responses
AccountFactorHoldViewProblemDetailsProblemDetailsAccountMerge
/api/v1/account/merge/sessionsStart a merge session naming the account to retire into the caller's own.
<b>The surviving account is taken from the validated token, never the body.</b> A self-service merge always folds another account into the caller's own, so accepting a client-supplied survivor would be an account-takeover primitive (name a victim as the retiring account, yourself as the survivor). Any `survivingAccountId` in the body is ignored; the domain re-asserts the same invariant so this cannot be bypassed.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
StartAccountMergeRequestasapplication/*+json,application/json,text/json
Responses
StartAccountMergeResponseProblemDetailsProblemDetailsProblemDetails/api/v1/account/merge/sessions/{id}/commitCommit the merge (retire + fold). Requires the session to be proven AND a fresh survivor step-up (WCAG 2.2 SC 3.3.4 error-prevention gate, debt-2026-07-03-226). Rejects the destructive confirm with 403 when the step-up is absent or invalid.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | — |
Request body
Not marked as required in the document.
CommitAccountMergeRequestasapplication/*+json,application/json,text/json
Responses
CommitAccountMergeResponseProblemDetailsProblemDetailsProblemDetailsProblemDetails/api/v1/account/merge/sessions/{id}/proveBind proof-of-control for one account of the session. Submit once per account; the session becomes `Proven` once both are bound.
The body carries the account being proven PLUS a second-factor proof enrolled on THAT account. The caller's own authenticated session is not evidence about the retiring account — which is, by construction, not the account they are signed in as — so the factor is verified against `accountId`, never against the caller.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | — |
Request body
Not marked as required in the document.
ProveAccountMergeRequestasapplication/*+json,application/json,text/json
Responses
ProveAccountMergeResponseProblemDetailsProblemDetailsProblemDetailsProblemDetails/api/v1/account/merge/sessions/{id}/statusRead the merge session's per-stage progress so the UI can render honest, discrete "visibly working" stages (rekey → move_records → unify_identity → repoint_consents) instead of an indeterminate busy state (debt-2026-07-03-226). Only the session initiator may read it.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | — |
Request body
No request body.
Responses
AccountMergeStatusResultProblemDetailsProblemDetails/api/v1/account/merge/sessions/{id}/undoReverse a committed merge within the grace window.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | — |
Request body
No request body.
Responses
UndoAccountMergeResponseProblemDetailsProblemDetailsProblemDetails/api/v1/account/merge/{id}/policyResolve the organisation governance policy that governs THIS merge — the member-facing read behind the step-6 confirm gate (journey `account-merge-consolidate-duplicate-identities`, debt-2026-07-09-253). Returns the governing mode (`allow` | `require-approval` | `block`) and, when an organisation governs it, that organisation's display name.
The same resolver backs the server-side commit gate, so what the member is shown and what the server enforces cannot diverge. An ungoverned (personal) merge — the common case — resolves to `allow` with no organisation. Only the session initiator may read it: a merge session id would otherwise be an IDOR handle onto another member's organisation membership. Zero-knowledge: a mode and an organisation display name only — never org data.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | — |
Request body
No request body.
Responses
AccountMergeGovernanceResultProblemDetailsProblemDetailsProblemDetails/api/v1/account/merge/{id}/request-approvalEnqueue this merge for its surviving member's organisation to approve before it can commit (EPIC 7 governance seam, debt-2026-07-09-284). Flags the merge require-approval and feeds the org-console approval queue via an outbox integration event. Only the session initiator may request approval.
Calling this is <b>not</b> what makes the org gate apply. The commit gate resolves the governing organisation's policy directly, so a client that never calls this endpoint still cannot commit a merge a `require-approval` organisation governs. This endpoint is how the member puts their merge INTO that org's queue.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | — |
Request body
Not marked as required in the document.
RequestAccountMergeApprovalRequestBodyasapplication/*+json,application/json,text/json
Responses
ProblemDetailsProblemDetailsProblemDetailsProblemDetails/api/v1/account/merge/{id}/reverseReverse a committed merge within the grace window, returning the full reversal receipt (journey Step-7 "Undo merge", debt-2026-07-07-104). Exposed at the absolute route the delivered client calls — `POST /api/v1/account/merge/{id}/reverse`. Restores both accounts, instructs downstream consumers (via the reversal outbox event) to revert re-pointed grants and retract org notices, and reports the counts of each. Only the session initiator may reverse it; valid only while `ReversibleUntil` is open (else 409).
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | — |
Request body
No request body.
Responses
ReverseMergeResponseProblemDetailsProblemDetailsProblemDetails/api/v1/account/merge/{id}/reversibilityResolve the reversal posture that applies to THIS merge — `self-service`, `assisted-only` or `none`, with the window length in whole days (journey `account-merge-consolidate-duplicate-identities`, gap G-reversibility, debt-2026-08-10-003).
<b>Answerable before the destructive confirm.</b> That is the point of it: the confirm gate used to promise an unconditional 30-day self-service undo and the receipt then walked it back to "(assisted recovery)" — after the member could no longer decline. Both surfaces now render one posture resolved here. The posture is derived from what the reversal path actually enforces (the same resolved org policy `POST {id}/reverse` applies), so it can neither over-claim nor — as the client's unavailable-read fallback had to — under-claim. Only the session initiator may read it. Zero-knowledge: a posture and a window length.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | — |
Request body
No request body.
Responses
AccountMergeReversibilityResultProblemDetailsProblemDetailsProblemDetails/api/v1/account/merge/{id}/withdraw-approvalRetract a queued org-approval request on the member's own initiative, before the organisation has decided it (gap <b>G-withdraw</b>, `uxf-2026-08-12-017`). Moves the merge's approval state to `Withdrawn` and drops the org-console queue's held decision via an outbox integration event. Only the session initiator may withdraw.
This is the server half of the member's "submit-then-override" guard. The client releases the override <b>only</b> when this call succeeds: the behaviour it replaces cleared a device-local record and unlocked the override on a no-op, leaving the organisation holding a decision about a merge that had already run. <b>409</b> is returned when there is nothing to retract — the merge already committed or was undone, no request was ever made, or the organisation has already decided it. Withdrawing an already-withdrawn request returns <b>200</b>, so a retried call reads as the success it is.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | — |
Request body
No request body.
Responses
ProblemDetailsProblemDetailsProblemDetailsProblemDetailsAdminSetupPosture
/api/v1/admin/setup-posture/backfillAnnounces one keyset page of accounts' setup posture. Call repeatedly, passing the returned `nextAfterId`, until `complete` is true.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
BackfillSetupPostureRequestasapplication/*+json,application/json,text/json
Responses
BackfillSetupPostureResultProblemDetailsAdminUserRoles
/api/v1/admin/users/{idOrEmail}/rolesGrants request.Role to the user identified by idOrEmail.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
idOrEmail | path | string | yes | A user id (GUID) or email address. |
Request body
Not marked as required in the document.
SetUserRoleRequestasapplication/*+json,application/json,text/json
Responses
SetUserRoleResultProblemDetailsProblemDetailsProblemDetailsProblemDetails/api/v1/admin/users/{idOrEmail}/roles/{role}Revokes role from the user identified by idOrEmail.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
idOrEmail | path | string | yes | A user id (GUID) or email address. |
role | path | string | yes | Role name to revoke. |
Request body
No request body.
Responses
SetUserRoleResultProblemDetailsProblemDetailsProblemDetailsProblemDetailsAdminUsersDirectory
/api/v1/admin/usersPaginated directory search over email and name.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
query | query | string | no | — |
page | query | integer (int32) | no | — |
pageSize | query | integer (int32) | no | — |
Request body
No request body.
Responses
AdminUserPageDto/api/v1/admin/users/{userId}One user's identity and setup summary.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
userId | path | string (uuid) | yes | — |
Request body
No request body.
Responses
AdminUserSummaryDtoProblemDetailsAdulthoodHandover
/api/v1/identity/adulthood-handover/claim-contextRead the claim-context ("what you keep / what changes"). Seam: `getClaimContext`.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
guardianshipId | query | string (uuid) | no | — |
Request body
No request body.
Responses
ClaimVaultContextDtoProblemDetails/api/v1/identity/adulthood-handover/handover-confirmationRead the verified-majority handover confirmation: the live who-has-access set + the revocation date. Seam: `getHandoverConfirmation`.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
No request body.
Responses
HandoverConfirmationDtoProblemDetailsProblemDetails/api/v1/identity/adulthood-handover/key-claim/rekey-tokenMint the <b>one-shot</b>, 5-minute `purpose=majority-transition-rekey` token the now-adult presents to EPIC 1's `POST /api/v1/keys/wrapped-umk/majority-transition-rekey` to re-wrap their vault UMK under their own KEK (decision D-439, FR-30.011 / CC-070).
<b>Authorisation.</b> Requires an authenticated caller (class-level `[Authorize]`; no policy name, so nothing can 500 on an unregistered policy). The subject is taken from the caller's OWN claims via `GetUserIdFromClaims()` — there is deliberately no `{childId}`-style route or body parameter, so a guardian holding a perfectly valid session cannot request a key-custody token for the young adult: they would only ever mint one bound to their own (non-existent) majority claim and get a 404. <b>Status codes.</b> 404 when the caller has no majority claim (identical to the absent-record 404 elsewhere on this controller, so claim existence cannot be probed); <b>403</b> when the claim exists but is not yet `Verified` — the authority does not exist yet, which is a permission answer rather than the state-conflict 409 used for mis-sequenced challenge operations; 409 when a token was already issued (one shot). <b>Zero-knowledge.</b> The token authorises a re-wrap performed on the device. It carries only opaque identifiers; no key material passes through this endpoint.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
No request body.
Responses
ProblemDetailsProblemDetailsProblemDetailsProblemDetails/api/v1/identity/adulthood-handover/key-claim/resendResend the one-time code (rotates the code, no expiry). Seam: `resendKeyClaimCode`.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
No request body.
Responses
ResendKeyClaimCodeResultProblemDetailsProblemDetailsProblemDetails/api/v1/identity/adulthood-handover/key-claim/startStart the key-claim ceremony: issue a one-time-code identity-verification challenge (AAL2, no expiry). Seam: `startKeyClaim` (aka `verify/start`).
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
StartKeyClaimRequestBodyasapplication/*+json,application/json,text/json
Responses
StartKeyClaimResultProblemDetailsProblemDetails/api/v1/identity/adulthood-handover/key-claim/verifyVerify the submitted one-time code and, on success, re-wrap the vault UMK to the now-adult and record the minor→adult identity change + revocation proof. Seam: `verifyKeyClaim` (aka `verify/submit`). Returns `200` with `verified=false` on a code mismatch (with remaining attempts), so the client can prompt a retry.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
VerifyKeyClaimRequestBodyasapplication/*+json,application/json,text/json
Responses
VerifyKeyClaimResultProblemDetailsProblemDetailsProblemDetailsProblemDetailsAdviceAgencies
/api/v1/advice-agenciesThe advice-agency register.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
includeWithdrawn | query | boolean | no | Include agencies whose recognition has been withdrawn. |
Request body
No request body.
Responses
AdviceAgencyRow[]ProblemDetails/api/v1/advice-agenciesRecognises an organisation as an advice agency.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
RecogniseAdviceAgencyRequestasapplication/*+json,application/json,text/json
Responses
AdviceAgencyRowProblemDetailsProblemDetailsProblemDetails/api/v1/advice-agencies/{organizationId}/adviser-capabilitiesReplaces an agency's adviser permission ceiling — the set defined once at agency level rather than re-chosen by each client.
The set is a <b>ceiling, never a grant</b>. A relying service intersects it with what the client's own delegation conveyed, so widening it here can never authorise something a client did not consent to; narrowing it takes effect for every live case of the agency at once.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
organizationId | path | string (uuid) | yes | — |
Request body
Not marked as required in the document.
SetAdviceAgencyCapabilitiesRequestasapplication/*+json,application/json,text/json
Responses
AdviceAgencyRowProblemDetailsProblemDetailsProblemDetailsProblemDetails/api/v1/advice-agencies/{organizationId}/standingSuspends, restores or withdraws an agency's recognition.
A withdrawal de-authorises every adviser of the agency at once — authorisation is read as a conjunction, so no adviser row is rewritten — and reconciles their role claims, which are cached projections a still-valid token would otherwise carry past the withdrawal.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
organizationId | path | string (uuid) | yes | — |
Request body
Not marked as required in the document.
ChangeAdviceAgencyStandingRequestasapplication/*+json,application/json,text/json
Responses
AdviceAgencyRowProblemDetailsProblemDetailsProblemDetailsProblemDetailsAdviceAgencyAdvisers
/api/v1/advice-agency/advisersThe calling agency's own adviser register.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
includeInactive | query | boolean | no | Include revoked registrations (the audit view). |
Request body
No request body.
Responses
ProfessionalAdviserRegisterResultProblemDetails/api/v1/advice-agency/advisersRegisters an individual onto the calling agency's adviser register, unverified.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
RegisterProfessionalAdviserRequestasapplication/*+json,application/json,text/json
Responses
ProfessionalAdviserRowProblemDetailsProblemDetailsProblemDetailsProblemDetails/api/v1/advice-agency/advisers/{adviserUserId}/accreditationRecords or updates an adviser's own professional accreditation with their regulator.
Separate from identity verification: one establishes who they are, the other what they are accredited to do, and an agency commonly learns them at different moments. A creditor asked to accept a moratorium instruction is entitled to know which individual accreditation stands behind it, which the agency's own firm permission does not answer.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
adviserUserId | path | string (uuid) | yes | — |
Request body
Not marked as required in the document.
RecordAdviserAccreditationRequestasapplication/*+json,application/json,text/json
Responses
ProfessionalAdviserRowProblemDetailsProblemDetailsProblemDetailsProblemDetails/api/v1/advice-agency/advisers/{adviserUserId}/standingStands an adviser down, reinstates them, or revokes their registration.
A revocation is accepted even while the agency's own recognition is suspended: being unable to strike off a compromised adviser because your recognition lapsed would trap an agency at exactly the moment it most needs to act. It also ends every live case that adviser held <i>with this agency</i>, leaving those clients visibly unassigned rather than nominally advised by somebody who has left. A stand-down deliberately does <b>not</b> touch the caseload. A client whose adviser is on leave needs a named successor, so the handover stays an act a supervisor performs.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
adviserUserId | path | string (uuid) | yes | — |
Request body
Not marked as required in the document.
ChangeProfessionalAdviserStandingRequestasapplication/*+json,application/json,text/json
Responses
ProfessionalAdviserRowProblemDetailsProblemDetailsProblemDetailsProblemDetails/api/v1/advice-agency/advisers/{adviserUserId}/verificationRecords that the adviser's identity has been verified, issuing the `professional-adviser` claim and making them assignable to a client case.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
adviserUserId | path | string (uuid) | yes | — |
Request body
Not marked as required in the document.
VerifyProfessionalAdviserRequestasapplication/*+json,application/json,text/json
Responses
ProfessionalAdviserRowProblemDetailsProblemDetailsProblemDetailsProblemDetails/api/v1/advice-agency/caseloadThe calling agency's caseload.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
clientUserId | query | string (uuid) | no | Optional filter to one client — the "which of this agency's advisers held this case" read a regulator asks for. Combine with includeClosed for the full history. |
includeClosed | query | boolean | no | Include closed and handed-over assignments. |
Request body
No request body.
Responses
AdviserCaseloadResultProblemDetails/api/v1/advice-agency/caseloadPuts a named adviser on a client's case.
Refused when the agency already has a live assignment for this client: opening a second one would leave two advisers each believing they hold the case. Hand it over instead, so the change of hands is recorded.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
AssignAdviserToCaseRequestasapplication/*+json,application/json,text/json
Responses
AdviserCaseAssignmentRowProblemDetailsProblemDetailsProblemDetails/api/v1/advice-agency/caseload/{clientUserId}/endCloses a client's case with no successor.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
clientUserId | path | string (uuid) | yes | — |
Request body
Not marked as required in the document.
EndAdviserCaseAssignmentRequestasapplication/*+json,application/json,text/json
Responses
AdviserCaseAssignmentRowProblemDetailsProblemDetailsProblemDetails/api/v1/advice-agency/caseload/{clientUserId}/reassignHands a client's case from its current adviser to another adviser of the same agency — the caseload reassignment the journey needs when an adviser goes on leave or leaves.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
clientUserId | path | string (uuid) | yes | — |
Request body
Not marked as required in the document.
ReassignAdviserCaseRequestasapplication/*+json,application/json,text/json
Responses
AdviserCaseAssignmentRowProblemDetailsProblemDetailsProblemDetailsProblemDetailsAssist
/api/v1/identity/assist/actionsRecord a delegate-attributed assist action against an active session. The helper is always the authenticated caller (audit attribution). Returns `409` when the session has no active grant or is held by a different helper.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
RecordAssistActionRequestasapplication/*+json,application/json,text/json
Responses
RecordAssistActionResponseProblemDetailsProblemDetailsProblemDetailsProblemDetails/api/v1/identity/assist/consentRecord a live account owner's consent to be assisted at first-run. The granter (oversight attribution) defaults to the authenticated caller — the consenting owner. Idempotent: the same owner re-consenting for the same helper on a live session returns `200` with the existing grant id; a session id that carries any other grant returns `409 assist-session-taken`.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
ConsentToAssistRequestasapplication/*+json,application/json,text/json
Responses
ConsentToAssistResponseProblemDetailsProblemDetailsProblemDetailsProblemDetails/api/v1/identity/assist/non-custody-attestation/{sessionId}Read the verifiable non-custody attestation for an assist session — the oversight-status read that proves the helper never accessed the owner's key or recovery material. Degrades honestly (`nonCustodyAttested=false`) if any breach was ever recorded.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
sessionId | path | string (uuid) | yes | — |
Request body
No request body.
Responses
NonCustodyAttestationDtoProblemDetailsProblemDetails/api/v1/identity/assist/sessions/{sessionId}/actionsList the delegate-attributed action records for an assist session (the oversight-status action feed).
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
sessionId | path | string (uuid) | yes | — |
Request body
No request body.
Responses
AssistActionDto[]ProblemDetails/api/v1/identity/assist/{grantId}/revokeRevoke a consent-to-assist grant (clean teardown — "assistance ended").
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
grantId | path | string (uuid) | yes | — |
Request body
Not marked as required in the document.
RevokeAssistRequestBodyasapplication/*+json,application/json,text/json
Responses
RevokeAssistResultProblemDetailsProblemDetailsAssistedRecovery
/api/v1/auth/assisted-recovery/requestsRaise a delegated assisted-recovery request. Always returns `202 Accepted` with an opaque request reference for a well-formed request — a deliberate enumeration-safety property (the caller cannot distinguish a real managed identity from an unknown/unmanaged one). A malformed body returns `400` via the platform ProblemDetails handler (API-003) — including a `reason` the endpoint does not recognise, which is refused rather than rewritten (#8916). Omitting `reason` altogether is still accepted and defaults to `locked`.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
AssistedRecoveryRequestBodyasapplication/*+json,application/json,text/json
Responses
AssistedRecoveryRequestResponseProblemDetails/api/v1/auth/assisted-recovery/requests/{requestRef}Read the current state of a delegated assisted-recovery case — journey step 1b, the logged-out, re-enterable status surface. Returns metadata only.
`[AllowAnonymous]` (SEC-002, explicit and inherited from the class): the subject is locked out and holds no token, so the opaque request reference is the only credential available to them. Rate-limited under the platform default policy (`essence-default`) — annotated explicitly rather than relied on implicitly, because this endpoint's risk profile is materially different from the raise endpoint's. <b>Zero-knowledge.</b> The response carries the reference, the case status, the subject's own stated reason, a machine rejection-reason slug, and two timestamps. It carries no email, no organisation identity, no helpdesk approver identity, no proofing evidence and no key material. <b>Security trade-off — stated, not hidden.</b> The raise endpoint returns a uniform `202` with an opaque reference whether or not the work email resolves to a real managed identity. This endpoint makes those two cases distinguishable <em>to the holder of a reference</em>: a reference minted for a real managed identity resolves, while a synthetic one returns `404`. That is an account-existence / org-membership oracle for anyone who can submit an email and then poll the reference they were handed back. It was accepted rather than eliminated because the alternative — refusing the subject any view of their own case — is the gap this endpoint exists to close, and because the positive case is <b>loud</b>: minting a resolvable reference also creates a visible entry in that organisation's helpdesk queue, so the probe is not silent. The residual exposure is further bounded by per-IP rate limiting and by the reference being an unguessable 128-bit value (a reference cannot be <em>enumerated</em>, only replayed after being issued). A stricter, distributed, per-reference limiter for this endpoint is a real improvement that is NOT in place: the service currently registers only the platform default policy.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
requestRef | path | string (uuid) | yes | — |
Request body
No request body.
Responses
AssistedRecoveryStatusResponseProblemDetails/api/v1/auth/assisted-recovery/requests/{requestRef}/completeComplete a delegated assisted recovery — journey step 4. The subject redeems the CC-061 authorise-only recovery token their helpdesk's authorisation minted and sets a new, client-derived credential.
`[AllowAnonymous]` (SEC-002, explicit): the subject is by definition unable to authenticate — that is the situation being recovered from. The endpoint is not unauthenticated in effect: possession of the single-use recovery token bound to an <em>authorised</em> case IS the credential, and both conditions are checked server-side before anything is mutated. <b>A helpdesk agent cannot complete a recovery here.</b> No role, claim, or org membership grants access to this endpoint — there is nothing to grant, because it is anonymous. What it requires is the token minted by the escrow grant and bound to the case, which is not something authorising confers on the authoriser. <b>Zero-knowledge.</b> `newPasswordHash` is the client-derived verifier, the same contract as `POST /auth/change-password`. No plaintext credential and no key material is ever transmitted; the subject re-wraps their own keys on-device. <b>Out-of-band delivery of the token to the subject is NOT implemented in this service.</b> The escrow grant returns the token reference to the authorising admin; getting it to the locked-out subject is a Notifications-owned seam. This endpoint validates whatever token the subject presents — it does not, and must not, mint or resend one.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
requestRef | path | string (uuid) | yes | — |
Request body
Not marked as required in the document.
CompleteAssistedRecoveryBodyasapplication/*+json,application/json,text/json
Responses
CompleteAssistedRecoveryResponseProblemDetailsProblemDetailsProblemDetailsAuth
/api/v1/auth/account/deactivateCloses the authenticated user's account at their own request (holder-account lifecycle procedure §3 T5). Requires a fresh GPG 44 medium step-up (DVS-7.2b).
The closure schedules the crypto-shred of the account's wrapped keys, recovery shares and ciphertext for the end of the 14-day grace window (DVS-7.2), so a bearer token alone is not enough: a fresh (≤ 5 minutes) `act=account-deactivation` elevation on `X-Step-Up-Token` (Essence.Identity.Auth.Api.Security.IAccountClosureStepUpGate), proved with a passkey, an authenticator-app or text-message code, or the password for an account with none of those; never an emailed or backup code. The closure alert's email carries a single-use link that cancels it until Essence.Identity.Auth.Application.Commands.DeactivateUserResult.CancelBy (`POST account/closure/cancel`), because a closed account cannot sign in.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
No request body.
Responses
DeactivateUserResultProblemDetailsProblemDetails/api/v1/auth/discoverGlobal home-realm discovery broker (EPIC 9 FR-09.032/033). Resolves a sign-in identifier — a general user's email, or an org-branded `host` — against the <b>EPIC 3 Global Registry only</b>, and returns where the sign-in should be brokered to complete: the resolved instance's OIDC authorize endpoint, the registry-signed short-TTL realm descriptor, and an opaque continuation `state`.
Microsoft.AspNetCore.Authorization.AllowAnonymousAttribute — discovery necessarily runs BEFORE authentication. <b>No credentials transit Global (FR-09.033).</b> This endpoint issues a REDIRECT TARGET, nothing more. The completing instance authenticates the user and mints the token with its own `iss_instance`, which is what lets EPIC 3's `FederationTrustGate` govern downstream acceptance. Global never sees a password, an authorization code, or key material. <b>Enumeration-safety in body AND timing (NFR-09.020).</b> Every outcome — resolved, unknown identifier, unbound org host, registry unreachable — returns 200 with the identical response shape, and an unresolved lookup is answered with the region-default realm rather than an empty or error result. An unbound org host falls back to the registry's own default-region descriptor (a second registry call) specifically so the fallback carries a real signature: a fallback with an empty `realmToken` would be as good an oracle as a 404. Every response is then padded to a configured floor, because a registry hit does strictly more work than a miss and response time would otherwise leak what the body does not. <b>Keyed on the DOMAIN, never the local-part (#8633).</b> A submitted `email` is reduced to its domain in-process, and only the domain reaches the registry; the address is never stored, logged, or forwarded. Clients that prefer not to send the address at all may supply `domain` directly. Resolution used to key on the SHA-256 of the whole address, which is no less zero-knowledge and was still an account-existence oracle — a hash does not anonymise an input the caller chooses, so the region came back as a statement about that named individual, disclosing which sovereign holds their vault to an anonymous stranger. FR-09.035 already keys org SSO discovery on the work-email domain only, for this reason.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
DiscoverRealmRequestasapplication/*+json,application/json,text/json
Responses
DiscoverRealmResponse/api/v1/auth/email/resend-otp(Re)issues an in-app email-verification OTP for the authenticated user (in-app-otp-email-verification). Rate-limited per user per hour.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
No request body.
Responses
ResendEmailVerificationOtpResultProblemDetailsProblemDetails/api/v1/auth/email/resend-otp/by-emailSends a fresh registration email-verification code to an address, WITHOUT a session (#7539) — the companion to M:Essence.Identity.Auth.Api.Controllers.AuthController.VerifyEmailOtpByEmail(Essence.Identity.Auth.Api.Controllers.VerifyEmailOtpByEmailRequest,System.Threading.CancellationToken) for a code that expired while the tab was closed.
`[AllowAnonymous]` (SEC-002, explicit) for the same reason as its sibling: no session exists. The answer is the SAME on every path — registered or not, verified or not, inside the account's 5/hr allowance or past it — so this is not an existence oracle and a 200 is never a promise that a message was sent. The account's own allowance still governs delivery, and a per-address burst ceiling inside the handler bounds how fast a stranger can put mail in somebody else's inbox.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
ResendEmailVerificationOtpByEmailRequestasapplication/*+json,application/json,text/json
Responses
ProblemDetailsProblemDetails/api/v1/auth/email/verify-otpVerifies the authenticated user's email using the in-app OTP code (in-app-otp-email-verification). On success the caller's session tokens are rotated so they reflect the verified state.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
VerifyEmailOtpRequestasapplication/*+json,application/json,text/json
Responses
VerifyEmailOtpResultProblemDetailsProblemDetails/api/v1/auth/email/verify-otp/by-emailRedeems a registration email-verification code WITHOUT a session (#7539) — the route back for someone who closed the tab at the email gate.
`[AllowAnonymous]` (SEC-002, explicit). The caller has, by definition, no session: that is the entire condition this endpoint exists to serve. Registration emails only the 6-digit code, and until this existed the ONLY endpoint that could spend it was the `[Authorize]` twin above — so closing the browser tab created an account that could neither be signed into (the address is unverified) nor re-registered (the address is taken). AC-44.006 / FR-44.003 promise a sign-up can be resumed after closing the browser; the onboarding session honoured that, this gate could not. <b>It issues no session.</b> On success the email is verified and the caller is told to sign in — no access token, no refresh token, no cookie. Possession of a mailbox proves an address; it does not authenticate a person, and a 6-digit emailed code must never become a factor that mints a session around the password. <b>Uniform negatives.</b> Unknown address, no outstanding code, wrong code, expired code, exhausted attempts and an already-verified address all return the IDENTICAL 400 — one title, no detail — so the response is not an oracle for the account's verification or code state, and since `POST /register` answers uniformly (#7225, on by default since DVS-4.12) it is one of the anonymous sign-up steps that must not tell a registered address from a new one either. Rate-limited twice: the platform default per IP (`essence-default`, SEC-004) and a per-address ceiling inside the handler that is charged before any lookup, so a caller past it costs nothing and an unregistered address reaches it at the same count as a registered one. The outstanding code keeps its own per-code attempt cap underneath both.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
VerifyEmailOtpByEmailRequestasapplication/*+json,application/json,text/json
Responses
VerifyEmailOtpByEmailResponseProblemDetailsProblemDetails/api/v1/auth/loginAuthenticates a user and returns access/refresh tokens.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
LoginCommandasapplication/*+json,application/json,text/json
Responses
LoginResultProblemDetailsProblemDetailsProblemDetails/api/v1/auth/login-methodsRegion-aware login-method presentation policy (EPIC 9 FR-09.036). Returns the ordered list of login methods the completing instance should present for a given region — organisation enterprise SSO first (when a federated + entitled work-email `domain` is supplied), then the region national IdP (AE → UAE PASS, GB → GOV.UK One Login), then passkey + email — honouring the org's SSO-only enforcement. The login UI renders from this list instead of a hardcoded button set. Anti-enumeration: an unknown/unfederated domain simply yields the general-user list (no org SSO), identical to supplying no domain.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
region | query | string | no | Completing instance region (ISO-3166 alpha-2, e.g. "GB"). Optional — an empty/missing region falls back to the universal method set (passkey + email) rather than a validation error, since ApiController model binding would otherwise reject a non-nullable string as a required field. |
domain | query | string | no | Optional work-email domain (ZK — domain only, never local-part). |
Request body
No request body.
Responses
LoginMethodsResponse/api/v1/auth/login/device-approval/{token}Polls the outcome of a Tier A new-device approval request (spec §5.1). The new device calls this with the opaque token from the login response; while a trusted device has not yet decided it returns `{ status: "pending" }`. On the first `approved` poll it issues the session tokens exactly once; subsequent polls return `approved` without re-issuing.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
token | path | string | yes | The opaque approval-poll token. |
Request body
No request body.
Responses
PollDeviceApprovalResult/api/v1/auth/login/device-limitContinues a sign-in paused at the device allowance (ruling 2026-10-01): signs out the chosen devices and, if that frees a place, issues the session the paused sign-in earned.
Microsoft.AspNetCore.Authorization.AllowAnonymousAttribute (SEC-002, explicit): the person has proved their factors but holds no session on this device yet. Authorisation is possession of the single-use `deviceLimit.challengeToken`, the same footing as `login/mfa`. A choice that frees nothing answers `200` with `deviceLimitReached` and a rotated token.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
ContinueAfterDeviceLimitCommandasapplication/*+json,application/json,text/json
Responses
LoginResultProblemDetailsProblemDetails/api/v1/auth/login/mfaCompletes a login that required multi-factor authentication.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
CompleteMfaLoginCommandasapplication/*+json,application/json,text/json
Responses
LoginResultProblemDetailsProblemDetails/api/v1/auth/login/mfa/resendRe-issues the one-time code for a login that is paused on its second factor (#6166).
Microsoft.AspNetCore.Authorization.AllowAnonymousAttribute (SEC-002, explicit): the caller has cleared the password factor but has no session yet, so the authenticated send endpoints (`POST /api/v1/mfa/send/email`) are unreachable to it. Authorisation is possession of the pending challenge token — the same credential `login/mfa` accepts on this same anonymous footing, and the reason the verify screen previously had no resend at all. Always `200`, including when nothing was sent. The outcome is in `status` (an `OtpDeliveryStatus`): the whole point of this endpoint is that a screen can tell a rate limit from an expired attempt from a dead channel and say the right thing, which a bare 4xx cannot express. It also means a caller cannot use the status code to distinguish a live challenge token from a dead one.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
ResendLoginMfaCodeCommandasapplication/*+json,application/json,text/json
Responses
ResendLoginMfaCodeResultProblemDetails/api/v1/auth/logoutLogs out a user by revoking the session.
The request body is optional. A browser SPA has no refresh token available to JavaScript (it never leaves the httpOnly cookie / server), so its logout call sends NO body at all — it identifies the session purely from the caller's own JWT/cookie. When no refresh token is supplied, the caller MUST be authenticated; the session is then resolved from the authenticated access token's `jti` claim, never from client input. Callers that DO send a valid `{ "refreshToken": "..." }` body keep working exactly as before, without needing to be authenticated (e.g. logging out with an already- expired access token but a still-valid refresh token).
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
LogoutCommandasapplication/*+json,application/json,text/json
Responses
LogoutResultProblemDetailsProblemDetails/api/v1/auth/org-idp/resolveOrganisation SSO directory resolution (EPIC 9 FR-09.035) — the server side of the frontend `orgSsoResolution.ts` seam. Resolves the org IdP record from a verified work-email `domain` (ZK — keyed on the domain only, never the local-part). Returns `{ "org": null }` uniformly for an unknown OR a non-federated/disabled domain so org existence is not enumerable (NFR-09.020).
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
domain | query | string | no | Verified work-email domain, lower-cased. Optional — an empty or missing domain yields the same uniform `{ "org": null }` as an unfederated one. The parameter is nullable for the same reason as M:Essence.Identity.Auth.Api.Controllers.AuthController.GetLoginMethods(System.String,System.String,System.Threading.CancellationToken)'s `region` (ISS-5): under `[ApiController]` a non-nullable `string` query parameter is implicitly required, so model validation would reject the empty case with a 400 <i>before</i> the guard below ever runs — leaving that guard unreachable and making the empty domain distinguishable from every other input, contrary to NFR-09.020. |
Request body
No request body.
Responses
OrgIdpResolveResponse/api/v1/auth/password/changeChanges the authenticated user's password (FR-09.013). Requires the current password for re-authentication. On success ALL of the user's active sessions are revoked and the outstanding access tokens blacklisted — the client must re-authenticate.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
ChangePasswordRequestasapplication/*+json,application/json,text/json
Responses
ChangePasswordResultProblemDetailsProblemDetails/api/v1/auth/password/setSets the FIRST password on the authenticated account when it has none (a social / passkey-only account). Sibling of `password/change` (FR-09.013) for accounts with no current credential to re-authenticate against. `passwordHash` is the client-derived hash — exactly as on `register` — never a plaintext password; the server wraps it in Argon2id before persisting. Sessions are NOT revoked.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
SetPasswordRequestasapplication/*+json,application/json,text/json
Responses
ProblemDetailsProblemDetailsProblemDetails/api/v1/auth/recovery-phraseClears the authenticated user's recovery-phrase proof. Idempotent: clearing an account with no proof enrolled also returns `204`.
Requires a fresh (≤ 5 minutes) `act=recovery-settings-change` elevation (DVS-4.4c): removing the phrase takes a way back into the account away from the holder.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
No request body.
Responses
ProblemDetails/api/v1/auth/recovery-phrase/enrolEnrols (or re-enrols) the authenticated user's recovery-phrase proof. `recoveryProof` is the client-derived proof (hex, ≥ 64 chars) — never the phrase, never the seed; the server wraps it in Argon2id before persisting. Re-enrolment replaces the previous proof.
Requires a fresh (≤ 5 minutes) `act=recovery-settings-change` elevation on `X-Step-Up-Token` (DVS-4.4c): whoever enrols a phrase can later recover the account with it.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
EnrolRecoveryPhraseRequestasapplication/*+json,application/json,text/json
Responses
ProblemDetailsProblemDetails/api/v1/auth/recovery-phrase/tokenVerifies a recovery-phrase proof for a user who has forgotten their password and, on success, mints the one-shot, 5-minute `purpose=recovery-rewrap` token that MultiDeviceSync accepts on `GET /api/v1/keys/wrapped-umk/recovery-phrase` and `POST /api/v1/keys/wrapped-umk/recovery-rewrap`.
`[AllowAnonymous]` (SEC-002, explicit): the caller has, by definition, no session. Rate-limited under the platform default policy (`essence-default`, SEC-004) — the same policy every other anonymous credential surface in this service uses; a wrong proof against a real account also increments the account's brute-force lockout counter (FR-09.010/011), so this surface cannot be used to guess around the login lockout. <b>Enumeration-safe.</b> Unknown email, no recovery phrase enrolled, wrong proof, inactive and locked-out accounts all receive the IDENTICAL `401` ProblemDetails (`title = "Recovery phrase not accepted"`, no `detail`) after a full Argon2id verification, so neither the body nor the timing is an account-existence or recovery-enrolment oracle. <b>Zero-knowledge.</b> The proof is not the phrase and cannot derive the vault KEK; the token carries only opaque identifiers. Auth does not reset the password (FR-05.082).
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
RecoveryPhraseTokenRequestasapplication/*+json,application/json,text/json
Responses
RecoveryRewrapTokenResponseProblemDetailsProblemDetailsProblemDetails/api/v1/auth/refreshRefreshes an access token using a refresh token.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
RefreshTokenCommandasapplication/*+json,application/json,text/json
Responses
RefreshTokenResultProblemDetailsProblemDetails/api/v1/auth/registerRegisters a new user account.
`[AllowAnonymous]` (SEC-002, explicit): the caller has no account yet, by definition. <b>Uniform answer (#7225, EPIC 9 contract, when `Registration:UniformResponse` is on — the code default since DVS-4.12; staged off on Global, decision P-18).</b> The response is `202``{ "next": "verify-email" }`, byte-identical for a free address and a taken one. The body is a constant built here: it does not depend on anything the handler learned, so the two cases cannot drift apart through it. No tokens and no cookie. The account's first session comes from sign-in, after the emailed code is redeemed at `POST email/verify-otp/by-email`. A per-address ceiling answers `429`, and it is charged before the lookup. <b>Legacy answer (switch off).</b> `200` with tokens, or `409` for a taken address. This is the disclosure #7225 removes. It remains only until the callers that read the tokens have migrated.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
RegisterUserCommandasapplication/*+json,application/json,text/json
Responses
RegisterUserResultRegistrationAcceptedResponseProblemDetailsProblemDetailsProblemDetailsProblemDetails/api/v1/auth/registration/abandonReleases the authenticated user's <b>unverified</b> registration (#7964) so the address it holds can be registered again.
The exit from the email-verification gate for someone who mistyped their address. Until this existed the screen offered "sign out and register again", and that advice could not be followed: the unverified `users` row still held the address, so `POST /register` refused it with 409. The address was burned — permanently, and most painfully when the typo landed on somebody else's real address. <b>This releases; it does not amend.</b> FR-44.024 originally asked for an in-place email change. The ruling on #7964 amended it, because on this platform the email is the PBKDF2 salt behind both the stored credential and the UMK: amending it under a hash derived from the old address locks the user out and orphans their keys. Releasing costs the same password re-entry and risks nothing. Subject comes from the bearer token's `sub`, never the body (SEC-002 + the same pattern as `account/deactivate`) — a body-supplied id would make this an arbitrary-account eraser. Idempotent: releasing an already-released registration answers 204, because the effect the caller asked for is already true.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
No request body.
Responses
ProblemDetailsProblemDetails/api/v1/auth/users/{userId}/unlockUnlocks a locked user account. Requires admin role.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
userId | path | string (uuid) | yes | User ID to unlock |
Request body
No request body.
Responses
UnlockAccountResultProblemDetailsProblemDetailsProblemDetails/api/v1/auth/validate-tokenValidates an access token and returns user information. Used for service-to-service authentication.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
ValidateTokenQueryasapplication/*+json,application/json,text/json
Responses
TokenValidationDtoProblemDetails/api/v1/auth/verify-emailVerifies a user's email address from the link in the verification email.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
token | query | string | no | The single-use verification token from the email link. |
Request body
No request body.
Responses
VerifyEmailResultProblemDetailsBillingProfileDirectory
/api/v1/internal/directory/users/{userId}/billing-profileResolves the bill-to name and email of a user.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
userId | path | string (uuid) | yes | The user the invoice is addressed to. |
Request body
No request body.
Responses
BillingProfileDtoProblemDetailsProblemDetailsBiometricReenrolment
/api/v1/biometric-reenrolmentOpens a re-enrolment session for the caller's biometric-mismatch lockout and raises the re-establishment-required alert. Reachable while locked out: a recovery-scoped step-up token is a validly-signed Essence JWT and passes the bearer scheme, exactly like a full session (mirrors Essence.Identity.Auth.Api.Controllers.TakeoverController). The subject is taken from the caller's own `sub` claim, and the org from the `organization_id` claim when present.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
OpenBiometricReenrolmentRequestasapplication/*+json,application/json,text/json
Responses
BiometricReenrolmentResultProblemDetailsProblemDetails/api/v1/biometric-reenrolment/oversightThe org oversight worklist: members of the caller's org whose biometric re-enrolment is in-progress / stalled. Scoped strictly to the caller's own `organization_id` claim, so cross-org reads are impossible by construction (no route org to forge).
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
No request body.
Responses
BiometricReenrolmentOversightResultProblemDetails/api/v1/biometric-reenrolment/{assuranceRef}/advanceAdvances the caller's own in-flight session to a new coarse step.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
assuranceRef | path | string | yes | — |
Request body
Not marked as required in the document.
StepRequestasapplication/*+json,application/json,text/json
Responses
BiometricReenrolmentResultProblemDetailsProblemDetailsProblemDetails/api/v1/biometric-reenrolment/{assuranceRef}/resolveResolves the caller's own session terminally — re-established or cancelled.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
assuranceRef | path | string | yes | — |
Request body
Not marked as required in the document.
OutcomeRequestasapplication/*+json,application/json,text/json
Responses
BiometricReenrolmentResultProblemDetailsProblemDetailsProblemDetailsCookieSession
/api/v1/auth/sessionEstablishes an httpOnly cookie session from the current JWT. The caller must present a valid JWT in the Authorization header. On success, issues: - `essence_auth`: httpOnly + Secure + SameSite=Strict cookie containing the JWT. - `essence_csrf`: readable (non-httpOnly) + Secure + SameSite=Strict cookie containing a random CSRF token. Returns 204 No Content on success.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
No request body.
Responses
ProblemDetailsProblemDetails/api/v1/auth/session/meReturns the authenticated user's basic identity claims. Used by frontends in cookie-session mode to determine `isAuthenticated` without parsing the JWT (which is httpOnly and invisible to JavaScript).
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
No request body.
Responses
SessionMeResponseProblemDetailsProblemDetails/api/v1/auth/session/revokeRevokes the cookie session by clearing both cookies.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
No request body.
Responses
ProblemDetailsCustodialEstablishmentPolicy
/api/v1/identity/custodial-establishment-policyRead the policy governing a jurisdiction.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
jurisdiction | query | string | no | ISO-3166 alpha-2 code. |
Request body
No request body.
Responses
CustodialPolicyResultProblemDetailsProblemDetailsCustodialOrders
/api/v1/identity/custodial-ordersList the caller's own submitted custodial orders, most recent first.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
No request body.
Responses
CustodialOrderResult[]/api/v1/identity/custodial-ordersSubmit a custodial order for verification.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
SubmitCustodialOrderRequestasapplication/*+json,application/json,text/json
Responses
CustodialOrderResultProblemDetailsProblemDetails/api/v1/identity/custodial-orders/pendingThe identity-authority queue: pending orders awaiting a recorded decision, oldest first (#13747). Every read is audited — who looked, not only who decided — because the list enumerates children subject to live custodial proceedings. The role spans every jurisdiction; jurisdiction can only narrow it.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
jurisdiction | query | string | no | — |
cursor | query | string | no | — |
pageSize | query | integer (int32) | no | — |
Request body
No request body.
Responses
ProblemDetailsProblemDetails/api/v1/identity/custodial-orders/{orderId}Read a custodial order's verification state.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
orderId | path | string (uuid) | yes | — |
Request body
No request body.
Responses
CustodialOrderResultProblemDetailsProblemDetails/api/v1/identity/custodial-orders/{orderId}/child-identityProvision the child's new legal identity under this verified order (debt-2026-08-13-220). The new principal carries no attribute, alias or key derived from the pre-adoption identity.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
orderId | path | string (uuid) | yes | — |
Request body
Not marked as required in the document.
ProvisionChildIdentityRequestasapplication/*+json,application/json,text/json
Responses
ProvisionChildIdentityResultProblemDetailsProblemDetailsProblemDetailsProblemDetails/api/v1/identity/custodial-orders/{orderId}/decisionRecord, as a platform operator, the decision the external authority made on a pending order. Restricted to identity-authority callers. The verdict is stored as operator-transcribed (#13747) — the operator did not decide, the authority did.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
orderId | path | string (uuid) | yes | — |
Request body
Not marked as required in the document.
DecideCustodialOrderRequestasapplication/*+json,application/json,text/json
Responses
CustodialOrderResultProblemDetailsProblemDetailsProblemDetailsProblemDetailsDelegateAccess
/api/v1/identity/delegate-access/grantsList delegate-access grants. `role=principal` (default) lists the grants the caller has issued ("who can act for me"); `role=delegate` lists the grants the caller holds (the "Act as" selector).
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
role | query | string | no | — |
Request body
No request body.
Responses
DelegateAccessGrantDto[]ProblemDetails/api/v1/identity/delegate-access/grantsGrant delegate access to an assistant / helper. The principal (the account owner delegating) is, by default, the authenticated caller. Idempotent: re-granting for the same delegate + delegation returns `200` with the existing grant id (never a duplicate).
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
GrantDelegateAccessRequestasapplication/*+json,application/json,text/json
Responses
ProblemDetailsProblemDetailsProblemDetails/api/v1/identity/delegate-access/grants/organisationEvery principal↔delegate pair in the caller's organisation, one keyset page at a time (#14066, debt-2026-08-11-791) — the exec office's roster: one assistant covering four executives, an executive's primary and holiday cover, a leaver whose every delegation must end. Ending a pair stays the per-grant revoke, so each keeps its own closure record. Organisation administrators only (`OrgOwner` / `OrgAdmin`). The organisation is bound from the caller's org claim; there is no parameter naming it, and an `X-Organization-Id` header that names a different one is refused rather than ignored.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
cursor | query | string | no | — |
pageSize | query | integer (int32) | no | — |
Request body
No request body.
Responses
OrganisationDelegateAccessPairDtoCursorResultProblemDetailsProblemDetailsProblemDetails/api/v1/identity/delegate-access/grants/{id}/revokeRevoke a delegate-access grant (clean teardown of the acting-as authority). Only the principal, the delegate, the issuer, or an administrator of an organisation both parties belong to may revoke; anyone else gets the same 404 as for an unknown id (#20297).
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | — |
Request body
Not marked as required in the document.
RevokeDelegateAccessRequestBodyasapplication/*+json,application/json,text/json
Responses
RevokeDelegateAccessResultProblemDetailsProblemDetails/api/v1/identity/delegate-access/sessionsEstablish a scoped acting-as session (the "Act as [Principal]" selection). The caller must be the grant's own delegate and the grant must be active. Returns a short-lived delegated-session token plus the acting-as bar context.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
EstablishActingAsSessionRequestasapplication/*+json,application/json,text/json
Responses
EstablishActingAsSessionResultProblemDetailsProblemDetailsProblemDetails/api/v1/identity/delegate-access/sessions/contextRead the live acting-as context the persistent "Acting as [Principal]" bar renders from. Only the grant's own delegate can read it; it degrades the instant the grant is revoked or expires (`isActive=false`).
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
grantId | query | string (uuid) | no | — |
Request body
No request body.
Responses
ActingAsContextDtoProblemDetailsProblemDetailsDelegatedAgents
/api/v1/identity/agentsLists the caller's own agents and their containment state.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
No request body.
Responses
DelegatedAgentDto[]ProblemDetails/api/v1/identity/agentsRegisters an AI agent to act on the caller's behalf. The credential secret is in the response body and is never retrievable again — only its hash is stored.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
RegisterDelegatedAgentRequestasapplication/*+json,application/json,text/json
Responses
RegisterDelegatedAgentResponseProblemDetailsProblemDetails/api/v1/identity/agents/tokenExchanges an agent credential for a short-lived agent session. Anonymous because the credential IS the authentication — an agent has no prior session to present.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
AgentTokenRequestasapplication/*+json,application/json,text/json
Responses
AgentTokenResponseProblemDetailsProblemDetails/api/v1/identity/agents/{agentReference}/keyRegisters — or replaces — the agent's EC P-256 public key (agent-gateway CONTRACTS §1). The body is one public JWK with exactly `kty`, `crv`, `x` and `y`; a JWK carrying private material (`d`) or any other member, key type or curve is refused 400. Once registered, every access token the agent is issued carries `cnf.jkt` = the key's RFC 7638 thumbprint, binding it to proof of possession. Callable only by the agent's own principal. An agent cannot set its own key: its token's `sub` is its reference, not a user id, so it never resolves to a caller.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
agentReference | path | string | yes | — |
Request body
Not marked as required in the document.
AgentPublicJwkRequestasapplication/*+json,application/json,text/json
Responses
AgentKeyResponseProblemDetailsProblemDetailsProblemDetailsProblemDetailsProblemDetails/api/v1/identity/agents/{agentReference}/suspendCuts an agent's credential and every live session it holds, for a named EPIC 12 incident, and returns the suspension reference the containment chain records. Callable by the agent's own principal (cutting off their own agent) or by an incident responder. Idempotent: a retried containment leg returns the same suspension reference rather than minting a second suspension.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
agentReference | path | string | yes | — |
Request body
Not marked as required in the document.
SuspendDelegatedAgentRequestasapplication/*+json,application/json,text/json
Responses
SuspendDelegatedAgentResponseProblemDetailsProblemDetailsProblemDetailsProblemDetailsDeviceApprovals
/api/v1/auth/device-approvalsLists the caller's own pending new-device approval requests.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
No request body.
Responses
PendingDeviceApprovalDto[]ProblemDetails/api/v1/auth/device-approvals/{id}/approveApproves a pending new-device request raised against the caller's account.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | — |
Request body
No request body.
Responses
ProblemDetailsProblemDetailsProblemDetailsProblemDetails/api/v1/auth/device-approvals/{id}/denyDenies a pending new-device request raised against the caller's account.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | — |
Request body
No request body.
Responses
ProblemDetailsProblemDetailsProblemDetailsProblemDetailsDevices
/api/v1/devicesGet all devices for the authenticated user
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
No request body.
Responses
DeviceDto[]ProblemDetails/api/v1/devices/{id}Get a specific device by ID
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | Device ID |
Request body
No request body.
Responses
DeviceDtoProblemDetailsProblemDetails/api/v1/devices/{id}Delete a device and revoke all its sessions
Requires a step-up elevation on `X-Step-Up-Token` (Essence.Identity.Auth.Api.Security.IDeviceRevocationStepUpGate, #8641): the revoke is irreversible, so a live session is not sufficient authority for it.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | Device ID |
deferRotation | query | boolean | no | The FR-01.049 re-keying choice the account holder made (debt-2026-06-18-331, journey `lost-device-revocation-and-session-hygiene`). `false` — the secure default, "Rotate my keys now". `true` — the user explicitly chose "Lock out later" and acknowledged the residual-access window, so the deferral and the window they accepted are recorded on the audit-anchored `DeviceRemovedEvent` (`RekeyAction == "deferred-warned"`) instead. The SPA (`multiDeviceSyncApi.removeDevice`) has always appended `?deferRotation=true` for the deferred path, but this action bound no such parameter, so the user's consent decision about their own device security was discarded while the dialog reported success and promised "this choice is recorded in your activity log". Binding it here keeps that promise, and matches MultiDeviceSync's `DevicesController.RemoveDevice` on the sibling path. |
reason | query | string | no | Why the owner is removing the device (FR-01.049, #11394): `user-initiated` (the default), `lost` or `stolen`. Recorded on the audit-anchored `DeviceRemovedEvent.Reason`; any other value is refused 400. |
Request body
No request body.
Responses
DeleteDeviceResultProblemDetailsProblemDetailsProblemDetails/api/v1/devices/{id}/blockBlock a device (suspicious activity or user-initiated)
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | Device ID |
Request body
Not marked as required in the document.
BlockDeviceRequestasapplication/*+json,application/json,text/json
Responses
BlockDeviceResultProblemDetailsProblemDetails/api/v1/devices/{id}/nameUpdate the friendly name of a device
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | Device ID |
Request body
Not marked as required in the document.
UpdateDeviceNameRequestasapplication/*+json,application/json,text/json
Responses
UpdateDeviceNameResultProblemDetailsProblemDetails/api/v1/devices/{id}/trustTrust a device ("Remember this device" functionality)
Requires a fresh (≤ 5 minutes) `act=recovery-settings-change` elevation on `X-Step-Up-Token` (DVS-4.4c): a trusted device skips new-device verification and can approve other devices' sign-ins, so marking one trusted changes how the account can be got back into.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | Device ID |
Request body
No request body.
Responses
TrustDeviceResultProblemDetailsProblemDetailsProblemDetailsDomainDetections
/api/v1/auth/domain-detectionsReturns the accounts detected on one of the caller's organisation's verified domains.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
domain | query | string | no | — |
Request body
No request body.
Responses
DomainDetectionResultProblemDetailsProblemDetailsProblemDetailsFederatedAccountLink
/api/v1/auth/federated-accounts/uae-passResolves (or provisions) the Essence account behind a verified UAE Pass subject.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
UaePassAccountLinkRequestasapplication/*+json,application/json,text/json
Responses
UaePassAccountLinkResponseProblemDetailsProblemDetailsProblemDetailsFieldAttestations
/api/v1/identity/attestations/contactLists every contact-field provenance attestation for the authenticated subject so the present primitive can stamp each outbound field in one call.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
No request body.
Responses
ContactFieldAttestationDto[]ProblemDetails/api/v1/identity/attestations/contactRecords (or refreshes) a contact-field provenance attestation for the authenticated subject. Seam: `contactAttestationApi.attest` (debt-2026-07-03-216).
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
AttestContactFieldRequestasapplication/*+json,application/json,text/json
Responses
FieldAttestationResultProblemDetailsProblemDetails/api/v1/identity/attestations/contact/{fieldKey}Reads the provenance attestation for one presented contact field of the authenticated subject. Seam: `contactAttestationApi.get` (debt-2026-07-03-216).
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
fieldKey | path | string | yes | — |
Request body
No request body.
Responses
ContactFieldAttestationDtoProblemDetailsProblemDetails/api/v1/identity/attestations/professionalRecords (or refreshes) a professional-credential attestation for the authenticated subject. Seam: `professionalAttestationApi.attest` (debt-2026-07-04-024).
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
AttestProfessionalCredentialRequestasapplication/*+json,application/json,text/json
Responses
FieldAttestationResultProblemDetailsProblemDetails/api/v1/identity/attestations/professional/{fieldKey}Reads the professional-body attestation metadata for one listing field of the authenticated subject. Seam: `professionalAttestationApi.get` (debt-2026-07-04-024).
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
fieldKey | path | string | yes | — |
Request body
No request body.
Responses
ProfessionalAttestationDtoProblemDetailsProblemDetailsGuardianships
/api/v1/identity/guardianshipsEstablishes a named guardianship over a supervised minor (Step 1 of the wizard).
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
EstablishGuardianshipRequestasapplication/*+json,application/json,text/json
Responses
GuardianshipResultDtoProblemDetailsProblemDetailsProblemDetails/api/v1/identity/guardianships/{childId}/guardiansReturns the current guardian roster for a supervised minor (per-child console).
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
childId | path | string (uuid) | yes | — |
Request body
No request body.
Responses
GuardianRosterDtoProblemDetails/api/v1/identity/guardianships/{childId}/guardiansAdds a scoped secondary guardian (co-guardian / successor-guardian / delegated-care-manager) to an active guardianship. A successor is added inactive (standby) until activated.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
childId | path | string (uuid) | yes | — |
Request body
Not marked as required in the document.
GuardianLinkDtoasapplication/*+json,application/json,text/json
Responses
GuardianRosterDtoProblemDetailsProblemDetailsProblemDetails/api/v1/identity/guardianships/{childId}/guardians/{guardianId}Removes a secondary guardian seat (the primary guardian can never be removed).
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
childId | path | string (uuid) | yes | — |
guardianId | path | string (uuid) | yes | — |
Request body
No request body.
Responses
GuardianRosterDtoProblemDetailsProblemDetailsProblemDetails/api/v1/identity/guardianships/{childId}/guardians/{guardianId}/activateActivates a standby successor guardian so it begins to hold authority.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
childId | path | string (uuid) | yes | — |
guardianId | path | string (uuid) | yes | — |
Request body
No request body.
Responses
GuardianRosterDtoProblemDetailsProblemDetailsProblemDetails/api/v1/identity/guardianships/{childId}/transitionCommits the majority authority-transfer for a supervised minor: revokes guardian authority and anchors the transition audit.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
childId | path | string (uuid) | yes | — |
Request body
Not marked as required in the document.
TransitionGuardianshipRequestasapplication/*+json,application/json,text/json
Responses
TransitionAuditResultDtoProblemDetailsProblemDetailsIdentityAssurance
/api/v1/identity/assuranceReads the full authoritative assurance record, or 404 when none exists yet.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
No request body.
Responses
AssuranceRecordResultProblemDetailsProblemDetails/api/v1/identity/assurance/community-vouchedLists accounts whose identity assurance rests on <b>community vouching</b>, with the level they hold and whether their assurance is current, expiring or stale — the oversight worklist for journey `community-vouching-onboarding-no-id` (debt-2026-06-06-143, and the admin half of debt-2026-06-06-140). Admin-scoped: this is a cross-account view, so it is gated on the platform-admin policy rather than on the caller being the subject. It returns no name, no email and no evidence — a level, a provenance, two instants and an opaque anchor reference per row. The <b>attester chain</b> (who vouched, from which organisation, and the anti-collusion verdict on the set) is EPIC 36's evidence and is deliberately not served here; the oversight surface reads it from EPIC 36 and says so when it is unavailable.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
limit | query | integer (int32) | no | — |
expiringWithinDays | query | integer (int32) | no | — |
Request body
No request body.
Responses
CommunityVouchedAccountsResultProblemDetailsProblemDetails/api/v1/identity/assurance/policyReturns the authoritative proofing policy for the authenticated account, or the documented per-actor default (`isDefault=true`) when none is recorded yet. Capability (b).
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
invitedByOrg | query | boolean | no | — |
orgName | query | string | no | — |
Request body
No request body.
Responses
ProofingPolicyResultProblemDetails/api/v1/identity/assurance/proofingInitiates an identity-proofing session for the authenticated account and returns it (an existing live session is returned rather than duplicated). Capability (c).
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
InitiateProofingRequestasapplication/*+json,application/json,text/json
Responses
ProofingSessionResultProblemDetails/api/v1/identity/assurance/proofing/{sessionId}/completeRecords the <b>subject-reported</b> outcome of their own proofing session. This endpoint can only record a non-success outcome (failure/abandonment). A successful proofing lifts the account's authoritative assurance level, so it must be adjudicated by the proofing provider — the subject cannot assert their own success. Attempting to do so returns 403.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
sessionId | path | string (uuid) | yes | — |
Request body
Not marked as required in the document.
CompleteProofingRequestasapplication/*+json,application/json,text/json
Responses
ProofingSessionResultProblemDetailsProblemDetailsProblemDetailsProblemDetails/api/v1/identity/assurance/recordRecords the identity assurance level the authenticated account has reached at first-run as the authoritative EPIC 9 record, establishing its proofing policy. Idempotent upsert. Capability (a)+(b).
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
RecordAssuranceRequestasapplication/*+json,application/json,text/json
Responses
AssuranceRecordResultProblemDetailsProblemDetailsProblemDetails/api/v1/identity/assurance/recovery-decisionRecords the account holder's first-run recovery decision (recovery set up vs deferred) on the authoritative assurance record so the compliance-evidence view can retrieve / filter / export it from the authoritative EPIC 9 store (debt-2026-07-09-022). Returns the updated record; 404 when no assurance record has been recorded yet.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
RecordRecoveryDecisionRequestasapplication/*+json,application/json,text/json
Responses
AssuranceRecordResultProblemDetailsProblemDetailsIdentityAttestedReprovision
/api/v1/auth/identity-attested-reprovisionBootstraps a fresh credential set authorised by a completed identity verification, and returns the immutable attestation binding the two together.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
IdentityAttestedReprovisionRequestasapplication/*+json,application/json,text/json
Responses
IdentityAttestedReprovisionResultProblemDetailsProblemDetailsProblemDetailsIdentityDirectory
/api/v1/internal/directory/orgs/{organizationId}/sso-coverageSizes the population an organisation's domain-keyed sign-in change would reach.
The EPIC 9 IdP calls this for the `affectedMemberCount` on the SSO-enforcement review step (FR-09.041, issue #7264) — the number an org admin is shown immediately before an irreversible, org-wide sign-in change. Auth answers it because enforcement is applied through the domain-keyed org-IdP directory and Auth is the service that holds the accounts on those domains. Carries no PII whatsoever — an aggregate count and the organisation's own proven-domain tally — and so is the least sensitive member of this controller, but it keeps the same in-mesh-only trust boundary and the platform default rate-limit policy (SEC-004) as its siblings rather than opting out of either.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
organizationId | path | string (uuid) | yes | The organisation whose coverage is being sized. |
domain | query | string[] | no | Optional, repeatable: the `allowed-domains` scope's domain set. Narrows the organisation's proven domains; never extends them. Omit for the whole organisation. |
Request body
No request body.
Responses
OrgSsoCoverageDtoProblemDetails/api/v1/internal/directory/users/{userId}/assurance-postureResolves a party's identity <b>assurance posture</b> — attested or not, at what level, by whom, and when.
Exists so a relying service can establish that a party is identity-attested <b>without that party asserting it</b> and without the service receiving any identity attribute (debt-2026-08-22-005, journey `reciprocal-field-disclosure-negotiation-between-contacts`). EPIC 6's reciprocal atomic-commit gate is the first caller: before two people's fields are disclosed to each other it asks the identity authority, rather than trusting a self-reported badge. <b>Non-PII by contract.</b> The response is a boolean, a level name, an attesting-source label and an instant. It deliberately does NOT carry the proofing policy, provenance, audit anchor or recovery disposition that the account holder's own `assurance` surface returns — a relying party learns that the person was attested, never how. Same trust boundary as the sibling routes on this controller: service JWT, in-mesh only over Istio STRICT mTLS, never gateway-exposed, platform default rate-limit retained because this is an enumeration surface by nature.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
userId | path | string (uuid) | yes | The party to resolve. |
Request body
No request body.
Responses
AssurancePostureResultProblemDetailsProblemDetails/api/v1/internal/directory/users/{userId}/identity-attributesResolves the matchable identity attributes (email / phone / name) for a user principal.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
userId | path | string (uuid) | yes | The user-principal id to resolve. |
Request body
No request body.
Responses
UserIdentityAttributesDtoProblemDetails/api/v1/internal/directory/users/{userId}/nameabilityWhether a principal can be <b>named to a third party</b> — i.e. whether a notice addressed to someone else could say who it is about.
Exists so a service that will later need to name this person can discover, at the moment the user is configuring the thing, that it will not be able to (debt-2026-08-27-145). EPIC 15's dead-man's-switch is the first caller: its welfare check tells a nominated contact who to check on, and fails closed when the holder recorded no name. Asking here moves that failure from the escalation — where nobody is contacted and the holder never learns — to the configuration screen, in front of the one person who can fix it. <b>Non-PII by contract.</b> Two booleans and the echoed id; the name itself is never returned. `GET recipients/{userId}/contact` remains the only route that discloses it, and only to the send path that must render it. That is what makes this one safe to call on an ordinary configuration write. Same trust boundary as the sibling routes: service JWT, in-mesh only over Istio STRICT mTLS, never gateway-exposed. A 200 is returned for an unknown id (`exists=false`) so the route cannot be used to enumerate which ids are real.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
userId | path | string (uuid) | yes | The user-principal id to check. |
Request body
No request body.
Responses
SubjectNameabilityDtoProblemDetailsIndividualAssistedRecovery
/api/v1/auth/assisted-recovery/individual/requests/{caseRef}/cancelCancel from the hold notice's link. Never staged off and never gated by a release stage.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
caseRef | path | string (uuid) | yes | — |
Request body
Not marked as required in the document.
IndividualRecoveryCancelBodyasapplication/*+json,application/json,text/json
Responses
IndividualRecoveryCancelResponseProblemDetails/api/v1/auth/assisted-recovery/individual/requests/{caseRef}/completeComplete after the hold: a new password verifier; every old authenticator and session revoked.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
caseRef | path | string (uuid) | yes | — |
Request body
Not marked as required in the document.
IndividualRecoveryCompleteBodyasapplication/*+json,application/json,text/json
Responses
IndividualRecoveryCompleteResponseProblemDetailsProblemDetails/api/v1/auth/assisted-recovery/individual/requests/{caseRef}/proofProve both codes. Starts the hold and returns the completion token, once.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
caseRef | path | string (uuid) | yes | — |
Request body
Not marked as required in the document.
IndividualRecoveryProofBodyasapplication/*+json,application/json,text/json
Responses
IndividualRecoveryProofResponseProblemDetailsInternalExecutorRoster
/api/v1/internal/directory/orgs/{orgId}/executor-officers/{officerUserId}/attestationWhether an officer is rostered and identity-verified by an organisation right now.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
orgId | path | string (uuid) | yes | The organisation whose roster to consult. |
officerUserId | path | string (uuid) | yes | The officer to resolve. |
Request body
No request body.
Responses
ExecutorOfficerAttestationResultProblemDetailsInternalGuardianshipCorroboration
/api/v1/internal/directory/minors/{minorUserId}/guardians/{guardianUserId}/corroborationWhether a person holds active guardian authority over a minor right now.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
minorUserId | path | string (uuid) | yes | The supervised minor. |
guardianUserId | path | string (uuid) | yes | The person claiming to be the minor's guardian. |
Request body
No request body.
Responses
GuardianshipCorroborationResultProblemDetailsProblemDetailsInternalOrgMembershipStanding
/api/v1/internal/directory/orgs/{orgId}/members/{userId}/standingWhether a user is an active member of an organisation, and whether they administer it.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
orgId | path | string (uuid) | yes | The organisation. |
userId | path | string (uuid) | yes | The user. |
Request body
No request body.
Responses
OrgMembershipStandingDtoProblemDetailsProblemDetailsInvitations
/api/v1/auth/invitations/acceptAccept an invitation: provision the invitee's account from the token + on-device password hash (zero-knowledge) and return an authenticated session.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
AcceptInvitationCommandasapplication/*+json,application/json,text/json
Responses
AcceptInvitationResultProblemDetailsProblemDetailsProblemDetails/api/v1/auth/invitations/declineDecline an invitation by its token.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
DeclineInvitationCommandasapplication/*+json,application/json,text/json
Responses
DeclineInvitationResultProblemDetailsProblemDetails/api/v1/auth/invitations/registerRegister an org invitation with EPIC 9's accountless-acceptance store. This is the service-to-service ingestion the org-side invitation seam calls when it mints the token. Idempotent by invitation id.
Admits only a first-party service principal named in Essence.Identity.Auth.Api.Controllers.InvitationIngestionPolicies.TrustedCallers (#11943). The body names the organisation, the invitee and the roles the accepted account is bound to, and nothing here can check those against a caller's own authority — so a user token, which bare `[Authorize]` admitted, could mint an invitation into any organisation carrying any role.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
RegisterOrgInvitationCommandasapplication/*+json,application/json,text/json
Responses
RegisterOrgInvitationResultProblemDetailsProblemDetails/api/v1/auth/invitations/{token}Read an invitation's detail by its opaque token — the invitation-detail card the essence-web AcceptInvitationPage renders before acceptance.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
token | path | string | yes | — |
Request body
No request body.
Responses
InvitationDetailDtoProblemDetailsJwks
/.well-known/jwks.jsonGet JSON Web Key Set (JWKS) for token validation. This endpoint is called by OAuth clients and resource servers to validate JWT tokens.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
X-Api-Version | header | string | no | — |
Request body
No request body.
Responses
JwksDocument/.well-known/openid-configurationGet OpenID Connect discovery document.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
X-Api-Version | header | string | no | — |
Request body
No request body.
Responses
OpenIdConfigurationMediumEnrolmentOptions
/api/v1/mfa/enrolment-optionsThe medium routes the server offers to set up, which are offered, and which the account has.
Held items open only from a medium session (DVS-4.3), so the set-up surfaces offer at least two medium routes — a passkey and an authenticator app — so that losing one does not drop the holder below it. A text-message code is offered once its enrolment is on (DVS-4.3b, `POST /api/v1/mfa/sms/enrolment`, after the number is verified) and listed as `not-available-yet` while it is staged off.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
No request body.
Responses
MediumEnrolmentOptionsDtoProblemDetailsProblemDetailsMemberInvitationAcceptance
/api/v1/auth/invitations/accept-as-memberAccept an invitation as the signed-in account it was issued to, joining that organisation.
No account is created, no password is set and no device is registered — the caller already has all three. The response carries a freshly minted access token for the caller's SAME session, so the organisation's `org_id` claim is usable immediately rather than only after the next refresh; the refresh token is untouched and the session continues.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
MemberInvitationTokenRequestasapplication/*+json,application/json,text/json
Responses
AcceptInvitationAsMemberResultProblemDetailsProblemDetailsProblemDetailsProblemDetails/api/v1/auth/invitations/decline-as-memberDecline an invitation as the signed-in account it was issued to.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
MemberInvitationTokenRequestasapplication/*+json,application/json,text/json
Responses
DeclineInvitationResultProblemDetailsProblemDetailsProblemDetailsProblemDetailsMfa
/api/v1/mfa/backup-codes/regenerateRegenerate backup codes for the authenticated user
Requires a fresh (≤ 5 minutes) `act=authenticator-enrolment` elevation (DVS-4.4b). A backup code completes a sign-in's second step and satisfies the step-ups that accept one, so issuing a new set adds an authenticator.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
No request body.
Responses
RegenerateMfaBackupCodesResultProblemDetailsProblemDetails/api/v1/mfa/disableDisable MFA for the authenticated user (requires a fresh step-up and the current password)
Requires a fresh (≤ 5 minutes) `act=second-factor-removal` elevation on `X-Step-Up-Token` (Essence.Identity.Auth.Api.Security.ISecondFactorRemovalStepUpGate; DVS-4.4d, TF 1.0 §7.3.1.c), proved with a passkey, an authenticator-app code or a text-message code (the factor being removed counts), never the password, an emailed code or a backup code. The password in the body is still checked as well. Without the elevation, a session and the password removed the factor and left the account at the password floor for every other medium gate. Checked before the password, so a refusal says nothing about whether the password was right.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
DisableMfaCommandasapplication/*+json,application/json,text/json
Responses
DisableMfaResultProblemDetailsProblemDetails/api/v1/mfa/enable/totpEnable TOTP (Google Authenticator) MFA for the authenticated user
Requires a fresh (≤ 5 minutes) `act=authenticator-enrolment` elevation on `X-Step-Up-Token`, proved with a factor the account already has (DVS-4.4b): the secret returned here IS the authenticator, so whoever receives it holds the factor. Confirming the staged enrolment (`POST /mfa/verify`) is not gated again: it needs a code from this secret, which only the elevated caller of this endpoint received.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
No request body.
Responses
EnableMfaWithTotpResultProblemDetailsProblemDetailsProblemDetails/api/v1/mfa/send/emailSend an OTP code via email to the authenticated user's verified email address
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
No request body.
Responses
SendEmailOtpResultProblemDetailsProblemDetailsProblemDetails/api/v1/mfa/send/smsSend an OTP code via SMS to the authenticated user's verified phone number
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
No request body.
Responses
SendSmsOtpResultProblemDetailsProblemDetailsProblemDetails/api/v1/mfa/statusReport whether the authenticated account has a second factor, and what remains of its backup codes.
Issue #4714. This surface carried three mutations and no read, so a client could CHANGE the MFA state and never OBSERVE it. Settings → Security consequently hardcoded its two-factor toggle to on — telling every user their authenticator app was enabled, true or not — and let them switch it off with no effect. There is no `enrolledAt`: the domain records no enrolment timestamp, and serving a plausible date for "when did you turn this on" is the class of invention this endpoint exists to remove. See Essence.Identity.Auth.Application.Queries.Mfa.MfaStatusDto.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
No request body.
Responses
MfaStatusDtoProblemDetailsProblemDetails/api/v1/mfa/verifyVerify an MFA code
Answers with a verdict, so a rejected code is a 200 whose `isValid` AND `success` are both `false` (#7240) — never a 200 that only one field contradicts. A caller must read a flag; the status code alone distinguishes only "we could not check" from "we did". See Essence.Identity.Auth.Application.Commands.Mfa.VerifyMfaResult for why the refusal is not a 401.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
VerifyMfaCommandasapplication/*+json,application/json,text/json
Responses
VerifyMfaResultProblemDetailsProblemDetailsMinorTransition
/api/v1/identity/minor-transition/identity-changeRead the minor→adult identity-change record. Seam: `getIdentityChange`.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
No request body.
Responses
IdentityChangeRecordDtoProblemDetailsProblemDetails/api/v1/identity/minor-transition/revocation-proofRead the exportable guardian-revocation proof. Seam: `getRevocationProof`.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
No request body.
Responses
RevocationProofDtoProblemDetailsProblemDetails/api/v1/identity/minor-transition/safe-recoveryInitiate guided step-up / assisted recovery after a failed majority verification. Seam: `initiateSafeRecovery`. The vault stays locked to the adult; control never reverts to the former guardian.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
InitiateSafeRecoveryRequestBodyasapplication/*+json,application/json,text/json
Responses
InitiateSafeRecoveryResultProblemDetailsProblemDetailsProblemDetailsNameChangeHistory
/api/v1/identity/history/name-changeList the account's committed verified-name-change history records (most recent first).
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
No request body.
Responses
VerifiedNameChangeView[]ProblemDetails/api/v1/identity/history/name-change/{auditRecordId}Read a single committed identity-history record by its audit record id.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
auditRecordId | path | string (uuid) | yes | — |
Request body
No request body.
Responses
VerifiedNameChangeViewProblemDetails/api/v1/identity/history/name-change/{auditRecordId}/exportExport a single committed identity-history record (portable, ZK-safe).
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
auditRecordId | path | string (uuid) | yes | — |
Request body
No request body.
Responses
NameChangeHistoryExportProblemDetailsNewDeviceFreezeLink
/api/v1/auth/takeover/new-device-alert-freezeFreeze the account a new-device alert's link was minted for, and sign out every device.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
NewDeviceFreezeLinkRequestasapplication/*+json,application/json,text/json
Responses
NewDeviceFreezeLinkResponseProblemDetailsOAuth
/api/v1/auth/oauth/{provider}/callbackHandles OAuth callback after user authorization at identity provider. Exchanges authorization code for tokens and signs in to, or creates, the account the external identity belongs to. It never links: linking an identity to an existing account starts at the authenticated `{provider}/link/authorize` and completes at `{provider}/link`, and a state minted for a link is refused here.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
provider | path | string | yes | Identity provider |
X-Api-Version | header | string | no | — |
Request body
Not marked as required in the document.
OAuthCallbackRequestasapplication/*+json,application/json,text/json
Responses
OAuthCallbackResultProblemDetailsProblemDetailsProblemDetails/api/v1/auth/oauth/{provider}/linkCompletes linking an OAuth identity provider to the authenticated user's account. Allows users to sign in using multiple identity providers. The state must have been started at `{provider}/link/authorize` by this same signed-in user; a sign-in state, or another user's link state, is refused before the authorization code is exchanged.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
provider | path | string | yes | Identity provider to link |
X-Api-Version | header | string | no | — |
Request body
Not marked as required in the document.
OAuthCallbackRequestasapplication/*+json,application/json,text/json
Responses
OAuthLinkResultProblemDetailsProblemDetailsProblemDetailsProblemDetailsOpenIdentityChanges
/api/v1/identity/primary-contact-changesThe caller's primary-contact changes still in progress (`Requested` / `NewAddressVerified`), most recent first.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
No request body.
Responses
PrimaryContactChangeView[]ProblemDetails/api/v1/identity/verified-name-changesThe caller's verified-name changes still in progress (`Requested` / `Reattested`), most recent first.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
No request body.
Responses
VerifiedNameChangeView[]ProblemDetailsOrgExecutorOfficers
/api/v1/orgs/executor-officersReturns the caller's organisation's executor roster.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
includeRemoved | query | boolean | no | Include removed officers (the audit view). Defaults to false. |
Request body
No request body.
Responses
ExecutorRosterResultProblemDetails/api/v1/orgs/executor-officersAdds an individual to the roster, unverified. Idempotent: re-adding someone already on the roster returns their existing row, and re-adding a removed officer reinstates them — unverified, because the reason they left may be the reason their evidence no longer holds.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
AddExecutorOfficerRequestasapplication/*+json,application/json,text/json
Responses
ExecutorOfficerRowProblemDetailsProblemDetails/api/v1/orgs/executor-officers/{officerUserId}/removalRemoves an officer from the roster and cascades that removal to every estate grant they hold.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
officerUserId | path | string (uuid) | yes | — |
Request body
Not marked as required in the document.
RemoveExecutorOfficerRequestasapplication/*+json,application/json,text/json
Responses
ExecutorOfficerRowProblemDetailsProblemDetailsProblemDetails/api/v1/orgs/executor-officers/{officerUserId}/verificationRecords that the officer's identity has been verified — the transition that makes the roster attest them to a consuming service.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
officerUserId | path | string (uuid) | yes | — |
Request body
Not marked as required in the document.
VerifyExecutorOfficerRequestasapplication/*+json,application/json,text/json
Responses
ExecutorOfficerRowProblemDetailsProblemDetailsProblemDetailsProblemDetailsOrgExpiringVerifications
/api/v1/orgs/{orgId}/expiring-verificationsReturns the org's expiring-verifications cohort within the look-ahead window (days), sorted by days-to-expiry ascending, with the aggregate counts the worklist header shows.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
orgId | path | string (uuid) | yes | — |
sortBy | query | string | no | — |
window | query | integer (int32) | no | — |
Request body
No request body.
Responses
ExpiringVerificationsCohortResultProblemDetails/api/v1/orgs/{orgId}/expiring-verifications/recordRecords (upserts) an org member verification into the cohort — the ingestion side of the base capability, called by the org proofing / verification seam so the worklist has data to act on.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
orgId | path | string (uuid) | yes | — |
Request body
Not marked as required in the document.
RecordVerificationRequestasapplication/*+json,application/json,text/json
Responses
ExpiringVerificationRowProblemDetailsProblemDetails/api/v1/orgs/{orgId}/expiring-verifications/request-recheckRequests a recheck for one or more verifications (per-row or bulk).
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
orgId | path | string (uuid) | yes | — |
Request body
Not marked as required in the document.
VerificationIdsRequestasapplication/*+json,application/json,text/json
Responses
VerificationActionResultProblemDetailsProblemDetails/api/v1/orgs/{orgId}/expiring-verifications/send-reminderSends a renewal reminder for one or more verifications (per-row or bulk).
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
orgId | path | string (uuid) | yes | — |
Request body
Not marked as required in the document.
VerificationIdsRequestasapplication/*+json,application/json,text/json
Responses
VerificationActionResultProblemDetailsProblemDetailsOrgGrantApprovals
/api/v1/orgs/{orgId}/grant-approvalsLists the grants awaiting the signed-in owner's co-sign. This is the collection root: `GET /api/v1/orgs/{orgId}/grant-approvals`.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
orgId | path | string (uuid) | yes | — |
Request body
No request body.
Responses
ProblemDetails/api/v1/orgs/{orgId}/grant-approvals/{grantId}/decisionRecords an approve/reject decision on a pending grant. On the final required approval the grant transitions to `active` and the delegate is notified server-side (outbox-backed integration event).
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
orgId | path | string (uuid) | yes | — |
grantId | path | string (uuid) | yes | — |
Request body
Not marked as required in the document.
GrantApprovalDecisionRequestasapplication/*+json,application/json,text/json
Responses
ProblemDetailsProblemDetailsProblemDetailsProblemDetailsOrgMemberInvitations
/api/v1/orgs/{orgId}/member-invitationsInvites a person to join this organisation as a member. The invitee receives an acceptance link by email; accepting provisions their account (they set their own password on their own device) and makes them a member, so their access token then carries this organisation's `org_id`.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
orgId | path | string (uuid) | yes | — |
Request body
Not marked as required in the document.
InviteOrganizationMemberRequestasapplication/*+json,application/json,text/json
Responses
InviteOrganizationMemberResultProblemDetailsProblemDetailsProblemDetailsOrgOperationalRoles
/api/v1/orgs/{orgId}/operational-rolesGrants an operational role to a member of this organisation.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
orgId | path | string (uuid) | yes | — |
Request body
Not marked as required in the document.
SetOperationalRoleRequestasapplication/*+json,application/json,text/json
Responses
SetOrgOperationalRoleResultProblemDetailsProblemDetailsProblemDetails/api/v1/orgs/{orgId}/operational-roles/catalogueThe roles this organisation may issue, with what each one lets the holder do.
Requires org-admin because the catalogue is the menu of authority an administrator is about to hand out; it is not a public description of the platform.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
orgId | path | string (uuid) | yes | — |
Request body
No request body.
Responses
OperationalRoleCatalogueEntryDto[]ProblemDetails/api/v1/orgs/{orgId}/operational-roles/holdersThe organisation's members who currently hold an operational role.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
orgId | path | string (uuid) | yes | — |
Request body
No request body.
Responses
OrgOperationalRoleHoldersResultProblemDetails/api/v1/orgs/{orgId}/operational-roles/{userId}/{role}Withdraws an operational role from a member.
Accepts a LAPSED membership that M:Essence.Identity.Auth.Api.Controllers.OrgOperationalRolesController.Grant(System.Guid,Essence.Identity.Auth.Api.Controllers.SetOperationalRoleRequest,System.Threading.CancellationToken) would refuse: an organisation must be able to strip a role from somebody it has just offboarded, which is exactly when the relationship is no longer live.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
orgId | path | string (uuid) | yes | — |
userId | path | string (uuid) | yes | — |
role | path | string | yes | — |
Request body
No request body.
Responses
SetOrgOperationalRoleResultProblemDetailsProblemDetailsOrgScopedAdminGrants
/api/v1/orgs/{orgId}/scoped-admin-grantsIssues a scoped-admin grant to a staff member. Under approval policy `none` the grant activates immediately (and the delegate is notified via the outbox); under `single-owner` / `dual-owner` it enters the co-sign gate and appears on other owners' approval worklists.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
orgId | path | string (uuid) | yes | — |
Request body
Not marked as required in the document.
IssueScopedAdminGrantRequestasapplication/*+json,application/json,text/json
Responses
ProblemDetailsProblemDetails/api/v1/orgs/{orgId}/scoped-admin-grants/mineThe CALLING delegate's own grant lifecycle status — the read behind the delegated-admin console's fail-closed gate (2→3 seam, gaps debt-2026-08-11-474 / debt-2026-08-11-807).
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
orgId | path | string (uuid) | yes | — |
Request body
No request body.
Responses
ProblemDetailsProblemDetailsOrgSharedDevices
OutOfBandProof
/api/v1/proof-of-control/challengesRead every challenge raised under one case reference.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
caseRef | query | string | no | — |
Request body
No request body.
Responses
OutOfBandProofChallengeView[]ProblemDetails/api/v1/proof-of-control/challengesIssue a challenge to a named account at that account's own recovery address.
Always returns 201 with a challenge id, whatever the subject turns out to be — an unknown account, an unverified contact and a reachable account are indistinguishable in the response, so this endpoint is not an account-existence oracle. An unreachable account simply never answers and lapses to `Unresponsive`.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
IssueProofChallengeRequestasapplication/*+json,application/json,text/json
Responses
IssueOutOfBandProofChallengeResultProblemDetailsProblemDetails/api/v1/proof-of-control/challenges/{challengeId}Read a challenge's state and the evidence class it currently yields.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
challengeId | path | string (uuid) | yes | — |
Request body
No request body.
Responses
OutOfBandProofChallengeViewProblemDetails/api/v1/proof-of-control/challenges/{challengeId}/answerAnswer a challenge. Deliberately requires NO authenticated session.
<b>Why anonymous.</b> The holder proving control is by definition someone who may not be able to sign in — that is the whole premise. Requiring a token here would reintroduce the barrier this capability exists to remove. <b>What guards it instead.</b> The challenge id is an unguessable GUID delivered to nobody, the code is a one-time secret delivered only to the account's own address, the comparison is constant-time over keyed hashes (SEC-005), and the aggregate caps wrong answers at `MaxAttempts` before refusing outright. The platform's `essence-default` IP rate limit (SEC-004) applies on top.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
challengeId | path | string (uuid) | yes | — |
Request body
Not marked as required in the document.
AnswerProofChallengeRequestasapplication/*+json,application/json,text/json
Responses
ProblemDetailsProblemDetailsProblemDetails/api/v1/proof-of-control/challenges/{challengeId}/cancelWithdraw an open challenge. Yields `Withdrawn` — no evidence either way.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
challengeId | path | string (uuid) | yes | — |
Request body
No request body.
Responses
OutOfBandProofChallengeViewProblemDetails/api/v1/proof-of-control/challenges/{challengeId}/extendExtend the answer window — the generous-timing control.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
challengeId | path | string (uuid) | yes | — |
Request body
Not marked as required in the document.
ExtendProofChallengeRequestasapplication/*+json,application/json,text/json
Responses
OutOfBandProofChallengeViewProblemDetailsProblemDetailsProblemDetailsPasswordBreachRange
/api/v1/auth/password/breach-rangeReturn the padded suffix list for a 5-character SHA-1 prefix.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
PasswordBreachRangeRequestasapplication/*+json,application/json,text/json
Responses
PasswordBreachRangeResponseProblemDetailsProblemDetailsProblemDetailsPhoneVerification
/api/v1/auth/phone/verificationTexts a six-digit code, valid for ten minutes, to the number on the caller's account.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
No request body.
Responses
PhoneVerificationSentResponseProblemDetailsProblemDetailsProblemDetails/api/v1/auth/phone/verification/confirmRedeems the code. Single use; five attempts per code; ten attempts per hour per account.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
ConfirmPhoneVerificationRequestasapplication/*+json,application/json,text/json
Responses
PhoneVerificationConfirmedResponseProblemDetailsProblemDetailsProblemDetailsPrimaryContactChanges
/api/v1/identity/primary-contact-changesRequest a primary-contact change; issues a challenge to the new address.
Requires a fresh (≤ 5 minutes) GPG 44 medium step-up elevation, `act=contact-change`, on `X-Step-Up-Token` (Essence.Identity.Auth.Api.Security.IContactChangeStepUpGate; DVS-4.4, TF 1.0 §7.3.1.c).
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
RequestPrimaryContactChangeRequestasapplication/*+json,application/json,text/json
Responses
RequestPrimaryContactChangeResultProblemDetailsProblemDetailsProblemDetails/api/v1/identity/primary-contact-changes/{changeId}Read the change session (masked; ZK-safe).
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
changeId | path | string (uuid) | yes | — |
Request body
No request body.
Responses
PrimaryContactChangeViewProblemDetailsProblemDetails/api/v1/identity/primary-contact-changes/{changeId}/cancelCancel the change during the trust window (retain the old contact).
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
changeId | path | string (uuid) | yes | — |
Request body
No request body.
Responses
CancelPrimaryContactChangeResultProblemDetailsProblemDetailsProblemDetails/api/v1/identity/primary-contact-changes/{changeId}/cascadeRead the per-consumer cross-service cascade projection.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
changeId | path | string (uuid) | yes | — |
Request body
No request body.
Responses
PrimaryContactCascadeViewProblemDetailsProblemDetails/api/v1/identity/primary-contact-changes/{changeId}/commitCommit cutover once the trust window has elapsed; emits the cascade event.
The cutover is the moment the contact details change, so it requires its own fresh (≤ 5 minutes) `act=contact-change` step-up elevation (DVS-4.4, TF 1.0 §7.3.1.c) — the one taken to open the change is at least a trust window old by now.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
changeId | path | string (uuid) | yes | — |
Request body
No request body.
Responses
CommitPrimaryContactChangeResultProblemDetailsProblemDetailsProblemDetailsProblemDetails/api/v1/identity/primary-contact-changes/{changeId}/resendRe-issue the challenge to the NEW address.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
changeId | path | string (uuid) | yes | — |
Request body
Not marked as required in the document.
ResendPrimaryContactChallengeRequestasapplication/*+json,application/json,text/json
Responses
ProblemDetailsProblemDetailsProblemDetailsProblemDetails/api/v1/identity/primary-contact-changes/{changeId}/revalidate-factorsRe-validate recovery factors / active shares during the trust window.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
changeId | path | string (uuid) | yes | — |
Request body
Not marked as required in the document.
RevalidatePrimaryContactFactorsRequestasapplication/*+json,application/json,text/json
Responses
ProblemDetailsProblemDetailsProblemDetails/api/v1/identity/primary-contact-changes/{changeId}/verify-new-addressProve control of the NEW address by submitting the one-time code.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
changeId | path | string (uuid) | yes | — |
Request body
Not marked as required in the document.
VerifyNewPrimaryContactAddressRequestasapplication/*+json,application/json,text/json
Responses
ProblemDetailsProblemDetailsProblemDetailsProblemDetailsPrincipals
/api/v1/principals/users/{userId}Validates that a user principal resolves to a real, active account.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
userId | path | string (uuid) | yes | The user-principal id to validate. |
Request body
No request body.
Responses
PrincipalValidationDtoProblemDetailsProbateRole
/api/v1/probate-role/grantsList the Probate Role grants the authenticated partner has assigned.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
No request body.
Responses
ProbateRoleGrantDto[]ProblemDetails/api/v1/probate-role/grantsGrant a Probate Role to a fee-earner. Matches the EPIC 15 → EPIC 9 wire contract: `200 { grantId }` on create, `409 { grantId }` on an idempotent re-grant.
<b>Service principals only</b> (debt-2026-08-25-234). FR-15.009.6 admits a Probate Role on two preconditions — a verified lifecycle event or a registered PoA — and neither is a fact this service holds. EstatePlanning does, and it is the only legitimate caller (`InboundEventConsumers` on PoA activation, and `ExecutorRenunciationService` after a court-recorded replacement). While this endpoint accepted a plain `[Authorize]` token, any authenticated user could POST themselves an Active grant over a stranger's estate — and the grant is not a bookkeeping row: `ProbateStepUpController` treats it as the role basis for reaching AAL2, so a self-issued grant was a working key. Following the `SafeguardingCasesController` precedent, the authority model is enforced here even though <b>provisioning</b>Essence.Platform.Infrastructure.Security.RoleClaims.LifecycleServiceAgent onto the EstatePlanning service account is separate deployment work — so it cannot be bypassed once that lands. The wire contract already anticipated this: the calling client documents `401 / 403 → throw (wrong service credential)` and soft-fails the grant rather than blocking PoA activation, so an unprovisioned token degrades to a logged, retried re-grant rather than an outage.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
GrantProbateRoleRequestasapplication/*+json,application/json,text/json
Responses
ProbateRoleGrantResponseProblemDetailsProblemDetailsProblemDetailsProbateRoleGrantResponse/api/v1/probate-role/grants/activeDoes the named attorney currently hold the Probate Role over the named subject?
The authorisation read behind EPIC 15's Probate Dashboard (FR-15.009.2, debt-2026-08-25-233). EPIC 9 owns the grant record, so the predicate is answered here rather than mirrored into EPIC 15 where it would go stale against a revocation. Service-principal gated for the same reason as the grant write: the answer names who holds authority over whose estate, which is not a fact an arbitrary authenticated caller may enumerate.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
attorneyUserId | query | string (uuid) | no | — |
subjectUserId | query | string (uuid) | no | — |
Request body
No request body.
Responses
ActiveProbateRoleResultProblemDetailsProblemDetails/api/v1/probate-role/grants/{id}/revokeRevoke a Probate Role grant before its expiry.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | — |
Request body
Not marked as required in the document.
RevokeProbateRoleRequestasapplication/*+json,application/json,text/json
Responses
RevokeProbateRoleResultProblemDetailsProblemDetailsProbateStepUp
/api/v1/auth/step-up/probate-grantInitiate a probate step-up. On success returns an `aal=2` step-up token recording the authority basis.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
InitiateProbateStepUpRequestasapplication/*+json,application/json,text/json
Responses
ProbateStepUpResponseProblemDetailsProblemDetailsProblemDetailsProblemDetails/api/v1/auth/step-up/probate-grant/assuranceReturn the achieved-vs-required assurance for the current probate session on an estate, for the release-gate surface.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
estateId | query | string (uuid) | no | — |
Request body
No request body.
Responses
ProbateAssuranceResultProblemDetails/api/v1/auth/step-up/probate-grant/challengeIssue a probate step-up challenge for the chosen accessible factor.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
SendProbateStepUpChallengeRequestasapplication/*+json,application/json,text/json
Responses
ProbateStepUpChallengeResponseProblemDetailsProblemDetailsProfileLocale
/api/v1/profile/preferred-localeReturns the signed-in subject's stored preferred locale (null when unset) and the supported locale set for the selector.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
No request body.
Responses
PreferredLocaleResultProblemDetails/api/v1/profile/preferred-localeSets (or changes) the signed-in subject's preferred communication locale. Idempotent — re-setting the current value returns 200 with `changed=false` and no event.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
SetPreferredLocaleRequestasapplication/*+json,application/json,text/json
Responses
PreferredLocaleResultProblemDetailsProblemDetails/api/v1/users/me/localeReturns the signed-in subject's stored preferred locale (null when unset) and the supported locale set for the selector.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
No request body.
Responses
PreferredLocaleResultProblemDetails/api/v1/users/me/localeSets (or changes) the signed-in subject's preferred communication locale. Idempotent — re-setting the current value returns 200 with `changed=false` and no event.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
SetPreferredLocaleRequestasapplication/*+json,application/json,text/json
Responses
PreferredLocaleResultProblemDetailsProblemDetailsProfileName
/api/v1/profile/nameReturns the holder's stored name and whether they may set it themselves.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
No request body.
Responses
ProfileNameResultProblemDetailsProblemDetails/api/v1/profile/nameSets the holder's first and last name. Setting the stored value again is a no-op.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
SetProfileNameRequestasapplication/*+json,application/json,text/json
Responses
ProfileNameResultProblemDetailsProblemDetailsProblemDetailsProblemDetailsProtectionStatus
/api/v1/users/me/protection-statusReturns the authenticated owner's aggregated protection status, or 404 when nothing has been provisioned yet (the client renders a neutral "not set up yet" state on absence).
<b>DVS-4.4g: a session opened with the alternate credential gets the 404.</b> Every component of this read model belongs to the same protection (the alternate passphrase, the backup view it opens, the trusted contact it alerts), so any of them would tell whoever holds that session that the protection exists. The session is answered exactly as an account that has set up nothing, by the same `NotFound()` on the same path, decided on the server from the session's sign-in tag — not left to the web panel hiding itself. The read still runs, so the two answers cost the same.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
No request body.
Responses
ProblemDetailsProblemDetails/api/v1/users/me/protection-status/alternate-credentialEnrols (or replaces) the owner's ALTERNATE credential — the second proof the cold sign-in accepts, for the `duress-passphrase-silent-alarm-and-decoy-unlock` journey (debt-2026-08-10-001).
Owner-scoped like every route on this controller: the subject comes from the JWT, so no caller can enrol an alternate credential onto someone else's account — which would otherwise be a backdoor into another person's sign-in. <b>DVS-4.4f: a fresh step-up first.</b> `LoginCommandHandler` accepts this credential as a sign-in password, so setting it is adding an authenticator (P-31): it needs a fresh (at most 5 minutes) `act=authenticator-enrolment` elevation on `X-Step-Up-Token`, proved at the account's own level (a passkey, authenticator-app or text-message code when it has one, else its password, P-23; never an emailed or backup code), with the P-32 exception for a federated-only account. Without it a stolen session could plant a sign-in password of its own choosing that outlives the session. The gate runs before the credential is read or hashed, and is staged with the other DVS-4.4 gates (`Auth:AuthenticatorEnrolmentStepUp:Enabled`, P-18). An enrolment raises the holder's neutral "a sign-in setting was changed" alert on both channels (DVS-7.4b path).
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
EnrolAlternateCredentialRequestasapplication/*+json,application/json,text/json
Responses
ProblemDetailsProblemDetailsProblemDetails/api/v1/users/me/protection-status/alternate-credentialWithdraws the owner's alternate credential. Idempotent: 204 whether or not one was enrolled, so the response never reveals whether the account had one.
<b>DVS-4.4f: deliberately NOT gated.</b> Withdrawing removes a way in; it lowers no sign-in or recovery path, so it is not the threat P-31 and P-37 answer. A step-up does nothing against a coercer standing over the holder (they can make the holder complete it), and a holder who has lost their factor must still be able to remove one someone else planted. A withdrawal the holder did not make does matter to them, so it raises the same neutral holder alert as enrolment, on both channels (P-26). <b>DVS-4.4g: a session opened with the alternate credential cannot withdraw it.</b> It gets the `204` an account with none gets, and nothing changes and nothing is announced — as for an account with none — while the handler reads, saves and logs as for any other call (Essence.Identity.Auth.Application.Commands.ProtectionStatus.WithdrawDuressCredentialCommand.FromAlternateCredentialSession). Otherwise the withdrawal alert in that session's own inbox would tell a coercer that a credential existed, and the session the protection exists for could disarm it.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
No request body.
Responses
ProblemDetails/api/v1/users/me/protection-status/trusted-contact/reinviteRe-invites (or re-picks) the owner's trusted contact after their consent lapsed or was revoked. Best-effort: emits the re-invite event for EPIC 66 to dispatch and returns 202.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
No request body.
Responses
ProblemDetailsRecipientDirectory
/api/v1/internal/directory/organisations/{organizationId}/notification-audienceResolves who an organisation-addressed notification is for: the organisation's active administrators, as user ids (#11198). EPIC 66 fans the notice out to them and resolves each one's contact through M:Essence.Identity.Auth.Api.Controllers.RecipientDirectoryController.GetRecipientContact(System.Guid,System.Threading.CancellationToken,System.Boolean) at send time.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
organizationId | path | string (uuid) | yes | The organisation whose audience is resolved. |
Request body
No request body.
Responses
OrganisationNotificationAudienceDtoProblemDetails/api/v1/internal/directory/recipients/{userId}/contactResolves the deliverable contact (email / phone) for a user principal.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
userId | path | string (uuid) | yes | The user-principal id to resolve. |
owedToClosedAccount | query | boolean | no | DVS-7.2b: `true` only for a notice the holder-account procedure owes a closed account (the closure notice with its cancel link, its cancellation, the closure lifecycle notices, the security alerts). Absent or false, a deactivated account is not deliverable (FR-66.127), as before DVS-7.2b. |
Request body
No request body.
Responses
RecipientContactDtoProblemDetailsRecipientLookup
/api/v1/auth/recipients/lookupResolves an email address to a share-capable user principal.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
RecipientLookupRequestasapplication/*+json,application/json,text/json
Responses
RecipientResolutionDtoProblemDetailsProblemDetailsReturningNational
/api/v1/identity/returning-national/queueReturns the business-admin bootstrap-acceptance queue — held cases awaiting approve / hold / decline, oldest first. Admin-only.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
limit | query | integer (int32) | no | — |
Request body
No request body.
Responses
ReturningNationalReceiptResult[]ProblemDetails/api/v1/identity/returning-national/queue/{decisionId}/resolveBusiness-admin resolves a held bootstrap case (approve / hold / decline). Approval credits the domestic assurance and meters the implied identity check. Admin-only.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
decisionId | path | string (uuid) | yes | — |
Request body
Not marked as required in the document.
ResolveReturningNationalBootstrapRequestasapplication/*+json,application/json,text/json
Responses
ReturningNationalReceiptResultProblemDetailsProblemDetailsProblemDetails/api/v1/identity/returning-national/{intakeId}/bootstrapRuns the returning-national bootstrap acceptance gate for the authenticated caller's intake. The origin jurisdiction, scheme and foreign LoA are those the caller's intake recorded (read from the Instance service) — the body cannot supply them (#14018). Returns the audited decision + user receipt. On an automatic accept the subject's authoritative identity assurance is credited to the mapped domestic level; otherwise the case is held for the business-admin queue.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
intakeId | path | string | yes | — |
Request body
Not marked as required in the document.
BootstrapReturningNationalRequestasapplication/*+json,application/json,text/json
Responses
ReturningNationalReceiptResultProblemDetailsProblemDetailsProblemDetailsRevocationSnapshot
/api/v1/auth/revocation-snapshotEvery revoked access token id that has not yet expired.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
No request body.
Responses
RevocationSnapshotDtoProblemDetailsSafeguardingAuthorities
SafeguardingOfficers
/api/v1/safeguarding-officersThe calling authority's own officer register.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
includeInactive | query | boolean | no | Include revoked designations (the audit view). |
Request body
No request body.
Responses
SafeguardingOfficerRegisterResultProblemDetails/api/v1/safeguarding-officersDesignates an individual onto the calling authority's register, unverified.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
DesignateSafeguardingOfficerRequestasapplication/*+json,application/json,text/json
Responses
SafeguardingOfficerRowProblemDetailsProblemDetailsProblemDetailsProblemDetails/api/v1/safeguarding-officers/directoryThe co-authoriser directory: every currently authorised officer, across every recognised authority, minus the caller.
<b>Gated on the investigator role, not on org administration.</b> The people entitled to see who may countersign are the people who may ask for a countersignature. Exposing it to org administrators generally would publish a list of safeguarding officers to every organisation on the platform. <b>The caller is excluded.</b> Dual control means an investigator may never be their own co-authoriser, so offering themselves would be offering a choice the domain then refuses.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
No request body.
Responses
CoAuthoriserDirectoryResultProblemDetails/api/v1/safeguarding-officers/{officerUserId}/standingStands an officer down, reinstates them, or revokes their designation.
A revocation is accepted even while the authority's own recognition is suspended: being unable to withdraw a compromised officer's designation because your recognition lapsed would trap a body at exactly the moment it most needs to act.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
officerUserId | path | string (uuid) | yes | — |
Request body
Not marked as required in the document.
ChangeSafeguardingOfficerStandingRequestasapplication/*+json,application/json,text/json
Responses
SafeguardingOfficerRowProblemDetailsProblemDetailsProblemDetailsProblemDetails/api/v1/safeguarding-officers/{officerUserId}/verificationRecords that the officer's identity has been verified, issuing the `safeguarding-investigator` claim and adding them to the co-authoriser directory.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
officerUserId | path | string (uuid) | yes | — |
Request body
Not marked as required in the document.
VerifySafeguardingOfficerRequestasapplication/*+json,application/json,text/json
Responses
SafeguardingOfficerRowProblemDetailsProblemDetailsProblemDetailsProblemDetailsSessionOperatingJurisdiction
/api/v1/sessions/current/operating-jurisdictionDeclares the jurisdiction the caller is working from, for this session.
Requires a fresh (≤ 5 minutes) `act=operating-jurisdiction-declaration` elevation on `X-Step-Up-Token`, proved with a passkey, an authenticator-app code or a text-message code. Checked before anything is read, so a refusal says nothing about the value. A later declaration replaces an earlier one and starts a new period.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
DeclareOperatingJurisdictionRequestasapplication/*+json,application/json,text/json
Responses
OperatingJurisdictionResponseProblemDetailsProblemDetailsProblemDetailsProblemDetailsProblemDetails/api/v1/sessions/current/operating-jurisdictionEnds this session's declaration before its period runs out.
The session's next token carries no `operating_jurisdiction`; a token already issued runs to its own expiry. Needs no step-up: it can only remove the claim.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
No request body.
Responses
OperatingJurisdictionEndedResponseProblemDetailsProblemDetailsSessions
/api/v1/sessionsGet all sessions for the authenticated user
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
No request body.
Responses
SessionDto[]ProblemDetails/api/v1/sessionsRevoke all sessions except the current one (logout from all other devices)
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
KeepCurrent | query | boolean | no | If true, keeps the current session active. Default is true. |
Request body
No request body.
Responses
RevokeAllSessionsResultProblemDetails/api/v1/sessions/wearable/revokeScope-revoke a single lost companion watch's delegated session (journey `lost-wearable-delegated-session-revoke`). Revokes ONLY the named watch's delegated JWT — the caller's phone and other devices stay signed in (unlike M:Essence.Identity.Auth.Api.Controllers.SessionsController.RevokeAllSessions(Essence.Identity.Auth.Api.Controllers.RevokeAllSessionsRequest) / FR-09.013). The delegated token is added to the revocation list so a found watch is provably inert immediately (`boundedInertBy`), and a durable `WearableSessionRevokedIntegrationEvent` is emitted on the outbox for incident audit. This is a safety action and is not billing-gated.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
RevokeWearableSessionRequestasapplication/*+json,application/json,text/json
Responses
RevokeWearableSessionResultProblemDetailsProblemDetails/api/v1/sessions/{id}Get a specific session by ID
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | Session ID |
Request body
No request body.
Responses
SessionDtoProblemDetailsProblemDetails/api/v1/sessions/{id}Revoke a specific session (logout from that session)
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | Session ID to revoke |
Request body
No request body.
Responses
RevokeSessionResultProblemDetailsProblemDetailsSharedDeviceAttestations
SmartLaunch
/api/v1/identity/smart/launch-contextsMint a one-time launch context. Called by a trusted EHR at the moment it launches a SMART app; the returned launch token is handed to the app and is redeemable exactly once.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
IssueSmartLaunchContextRequestasapplication/*+json,application/json,text/json
Responses
IssueSmartLaunchContextResultProblemDetailsProblemDetailsProblemDetails/api/v1/identity/smart/token-exchangeExchange an EHR's one-time SMART launch token for a scoped clinician session. The exchange is performed AS the clinician (the caller's bearer token), never as a service principal, so the resulting launch is attributable to a person.
Contracted refusals carry a `code`: `unregistered-iss` (400), `launch-token-invalid` (401), `scope-not-permitted` (403). A consumer distinguishes these from an outage by that code — a refusal is a decision, anything else is an unknown.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
SmartTokenExchangeRequestasapplication/*+json,application/json,text/json
Responses
SmartTokenExchangeResponseProblemDetailsProblemDetailsProblemDetails/api/v1/identity/smart/trusted-issuersList the trusted-EHR issuer registry.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
organizationId | query | string (uuid) | no | — |
Request body
No request body.
Responses
TrustedEhrIssuerDto[]ProblemDetailsProblemDetails/api/v1/identity/smart/trusted-issuersRegister an EHR issuer as trusted. Idempotent: re-registering an existing issuer returns its id rather than failing, so provisioning can be re-run.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
RegisterTrustedEhrIssuerRequestasapplication/*+json,application/json,text/json
Responses
RegisterTrustedEhrIssuerResponseProblemDetailsProblemDetailsProblemDetails/api/v1/identity/smart/trusted-issuers/{issuerId}/statusSuspend, withdraw, or reinstate a trusted issuer. Withdrawal is terminal; a suspension is reinstatable.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
issuerId | path | string (uuid) | yes | — |
Request body
Not marked as required in the document.
SetTrustedEhrIssuerStatusRequestasapplication/*+json,application/json,text/json
Responses
ProblemDetailsProblemDetailsProblemDetailsProblemDetailsSmsEnrolment
/api/v1/mfa/sms/enrolmentUse the verified number on the account for sign-in and step-up codes.
Requires a fresh (≤ 5 minutes) `act=authenticator-enrolment` elevation on `X-Step-Up-Token` (DVS-4.4b). Answers the backup codes once.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
No request body.
Responses
SmsEnrolmentResponseProblemDetailsProblemDetailsProblemDetailsStepUp
/api/v1/auth/step-upInitiate a step-up challenge for a privileged action. On success returns a short-lived `aal=2` step-up token, plus — for an irreversible action — the signed assertion its consuming service re-verifies server-side.
The token elevates the SESSION; the assertion authorises one irreversible OPERATION at a service that will not accept a bearer token it did not mint (debt-2026-08-19-008). Actions needing one also require Essence.Identity.Auth.Api.Controllers.InitiateStepUpRequest.PasswordHash: FR-15.008.7 demands password re-entry <i>and</i> a second factor, and the assertion attests to both.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
InitiateStepUpRequestasapplication/*+json,application/json,text/json
Responses
InitiateStepUpResponseProblemDetailsProblemDetailsProblemDetailsProblemDetails/api/v1/auth/step-up/email-codeEmail the one-time code a step-up for `action` will verify with `factor=email` (#8753). Unlike `POST /api/v1/mfa/send/email`, it serves an account whose MFA is off when the action's email floor applies — the only way such an account can obtain a `password-change` elevation.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
StepUpEmailCodeRequestasapplication/*+json,application/json,text/json
Responses
SendEmailOtpResultProblemDetailsProblemDetailsProblemDetailsProblemDetails/api/v1/auth/step-up/required-factorsReturns the step-up factors the calling session may use (intersection of the user's enrolled factors and the deployment-allowed factor set). With `?action=`, the factors a step-up for THAT action will accept — which for `password-change` includes the email floor for an account with no other factor (#8753). For `passkey-removal`, `contact-change` (GPG 44 medium, DVS-4.4) and `authenticator-enrolment` (DVS-4.4b) it never includes `email` or `backup-code`; an account with none of TOTP, SMS or a passkey is offered `password` instead.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
action | query | string | no | — |
Request body
No request body.
Responses
RequiredFactorsResponseProblemDetailsProblemDetailsStepUpOtp
/api/v1/auth/mfa/otp/requestSend a step-up one-time code over the chosen recovery channel.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
RecoveryOtpRequestDtoasapplication/*+json,application/json,text/json
Responses
RecoveryOtpRequestResponseProblemDetailsProblemDetailsProblemDetails/api/v1/auth/mfa/otp/verifyVerify a delivered step-up one-time code and, on success, receive the `recovery-initiate` elevation token it earns.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
RecoveryOtpVerifyDtoasapplication/*+json,application/json,text/json
Responses
RecoveryOtpVerifyResponseProblemDetailsProblemDetailsSubjectExportDelegation
/api/v1/subject-export-delegationMint a delegation credential for the authenticated caller, bound to one queued export.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
SubjectExportDelegationRequestasapplication/*+json,application/json,text/json
Responses
SubjectExportDelegationResponseProblemDetailsProblemDetailsSupportAccessAgents
/api/v1/developer/support-access/agentsEvery agent of the application, suspended ones included, oldest enrolment first. 404 when the caller does not administer the application; 503 when the Developer Portal cannot be asked.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
appId | query | string (uuid) | no | — |
Request body
No request body.
Responses
SupportAgentDto[]ProblemDetailsProblemDetails/api/v1/developer/support-access/agentsInvite one address to be an agent: 201 with `status: invited` and no `principalId`, identically whether or not the address has an Essence account (#21852). An address already invited to or enrolled on the application is 409. 400 names a refused field; 404 / 503 as for the list.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
EnrolSupportAgentRequestBodyasapplication/*+json,application/json,text/json
Responses
SupportAgentDtoProblemDetailsProblemDetailsProblemDetailsProblemDetails/api/v1/developer/support-access/agents/statusSuspend or reinstate several agents at once, atomically. Every id must be an agent of the application, or nothing changes (404 `support-agent-not-found`). `updated` counts the agents whose status actually changed.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
SetSupportAgentStatusRequestBodyasapplication/*+json,application/json,text/json
Responses
SupportAgentStatusChangeDtoProblemDetailsProblemDetailsProblemDetailsSupportAccessOversight
/api/v1/developer/support-access/sessionsOne page of the application's support-access sessions, newest first, as a JSON array (the shape the console reads). When there are more, the next page's cursor is in `X-Next-Cursor`; pass it back as `cursor`. `from`/`to` bound when the session was granted, `[from, to)`. An application the caller does not administer is the same 404 as an unknown one; 503 when the Developer Portal cannot be asked.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
appId | query | string (uuid) | no | — |
agentId | query | string (uuid) | no | — |
subject | query | string (uuid) | no | — |
from | query | string (date-time) | no | — |
to | query | string (date-time) | no | — |
cursor | query | string | no | — |
limit | query | integer (int32) | no | — |
Request body
No request body.
Responses
PartnerSupportSessionDto[]ProblemDetailsProblemDetailsProblemDetails/api/v1/developer/support-access/sessions/export.csvEvery session matching the filters as CSV — the partner's own audit pack. Refused (422) rather than truncated when it would exceed Essence.Identity.Auth.Application.Queries.DelegateAccess.ExportPartnerSupportSessionsQuery.MaxRows.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
appId | query | string (uuid) | no | — |
agentId | query | string (uuid) | no | — |
subject | query | string (uuid) | no | — |
from | query | string (date-time) | no | — |
to | query | string (date-time) | no | — |
Request body
No request body.
Responses
ProblemDetailsProblemDetailsProblemDetailsProblemDetailsSupportAccessPolicy
/api/v1/developer/support-access/policyThe application's policy. An application that has never saved one answers the closed posture (nobody may raise a request) with `configured: false`. 404 when the caller does not administer the application; 503 when the Developer Portal cannot be asked.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
appId | query | string (uuid) | no | — |
Request body
No request body.
Responses
SupportImpersonationPolicyDtoProblemDetailsProblemDetailsProblemDetails/api/v1/developer/support-access/policySave (create or replace) the application's policy. Every field is replaced. 400 names the field a value is refused for; 404 / 503 as for the read.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
SupportImpersonationPolicyRequestBodyasapplication/*+json,application/json,text/json
Responses
SupportImpersonationPolicyDtoProblemDetailsProblemDetailsProblemDetailsSupportAccessRequests
/api/v1/developer/support-access/requestsThe application's requests, newest first, keyset-paginated (#21871). An administrator of the application sees every request; an agent sees only its own. status and agentId narrow. 404 when the caller is neither an agent nor an administrator of the application, or it does not exist; 503 when the Developer Portal cannot be asked; 400 for a cursor this list did not issue.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
appId | query | string (uuid) | no | — |
status | query | string | no | — |
agentId | query | string (uuid) | no | — |
cursor | query | string | no | — |
pageSize | query | integer (int32) | no | — |
Request body
No request body.
Responses
ProblemDetailsProblemDetailsProblemDetails/api/v1/developer/support-access/requestsRaise a request. 201 with the request (`pending-supervisor` when the policy requires dual approval, else `pending-customer`); 422 `support-access-request-refused` with every `violations[]` entry when the policy refuses it, and nothing is recorded. 404 when the caller is neither the named agent nor an administrator of the application; 503 when the Developer Portal cannot be asked.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
RaiseSupportAccessRequestBodyasapplication/*+json,application/json,text/json
Responses
SupportAccessRequestDtoProblemDetailsProblemDetailsProblemDetailsProblemDetails/api/v1/developer/support-access/requests/{requestId}/approveA supervisor approves a request held `pending-supervisor`; it becomes `pending-customer` (#21869). 200 with the request; 404 when it does not exist or the caller is not on its application's roster; 403 `support-access-supervisor-not-eligible` with a `code` when the caller may not decide it; 409 when it is not awaiting a supervisor.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
requestId | path | string (uuid) | yes | — |
Request body
No request body.
Responses
SupportAccessRequestListItemDtoProblemDetailsProblemDetailsProblemDetailsProblemDetailsProblemDetails/api/v1/developer/support-access/requests/{requestId}/declineA supervisor declines a request held `pending-supervisor`, naming one of the decline reasons; it ends `declined` and the customer is never asked (#21869). Answers as M:Essence.Identity.Auth.Api.Controllers.SupportAccessRequestsController.Approve(System.Guid,System.Threading.CancellationToken); 400 for a reason that is not one of the decline reasons.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
requestId | path | string (uuid) | yes | — |
Request body
Not marked as required in the document.
DeclineSupportAccessRequestBodyasapplication/*+json,application/json,text/json
Responses
SupportAccessRequestListItemDtoProblemDetailsProblemDetailsProblemDetailsProblemDetailsProblemDetailsSupportAccessSessions
/api/v1/developer/support-access/sessions/{id}/terminateForce-terminate a support-access session of an application the caller administers. A session that does not exist, is not a support session, or belongs to an application the caller does not administer is the same 404. 503 when the Developer Portal cannot be asked who administers the application.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | — |
Request body
Not marked as required in the document.
TerminateSupportAccessSessionRequestBodyasapplication/*+json,application/json,text/json
Responses
ProblemDetailsProblemDetailsSupportAccessSubjectDecision
/api/v1/developer/support-access/requests/mineThe support-access requests awaiting the signed-in account holder's own decision, newest first. An empty array genuinely means none are pending.
A request still held for the partner's own supervisor is not listed — the customer has not been asked yet — nor is one past its 72-hour deadline, nor one already decided.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
No request body.
Responses
PendingSupportAccessRequestDto[]ProblemDetails/api/v1/developer/support-access/requests/mine/sessionsThe descriptive half of the support sessions over the caller's own account (#22084) — who is in the account, for which company, against which ticket — keyed by the consent ids of the grants they themselves issued.
<b>Why this is here and not on the partner's list.</b> The client used to read `GET …/requests?consentIds=…`, which is the partner-side list: scoped to an administrator of the application or an agent on its roster, and so unanswerable for the one audience that needs it — the customer whose account the session is over. The banner over a live session said "A support agent" with no company as a result. The subject's reads belong beside the subject's decision, under the capability the audience already holds. <b>Carries no authority.</b> No expiry, no status, no scopes — those are the EPIC 9 grant's, and ending the session works from the grant alone. A name that could not be resolved, or a descriptor read that failed outright, therefore cannot hide a live session or weaken its kill-switch. `consentIds` is a comma-separated list; ids naming no session of the caller's are simply absent from the answer, because answering an error for them would disclose which ids exist. An empty list is an empty array, not an error.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
consentIds | query | string | no | — |
Request body
No request body.
Responses
SupportAccessSessionDescriptorDto[]ProblemDetails/api/v1/developer/support-access/requests/{requestId}/decisionAnswer a request. `decision: "allow"` creates the time-boxed `support-impersonation` grant over the caller's own account and records it on the request; `decision: "deny"` ends the request and creates nothing.
`grantId` is optional and, when sent, is verified rather than trusted: a client that created the grant itself (as the browser client does) names it, and a value that is not the grant this request's consent binds is `409`.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
requestId | path | string (uuid) | yes | — |
Request body
Not marked as required in the document.
SupportAccessDecisionBodyasapplication/*+json,application/json,text/json
Responses
SupportAccessCustomerDecisionDtoProblemDetailsProblemDetailsProblemDetailsProblemDetailsSupportAgentInvitations
/api/v1/account/support-agent-invitationsThe caller's pending invitations, oldest first. Empty when the caller's address is not verified — an unverified address proves nothing about who holds it.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
No request body.
Responses
SupportAgentInvitationDto[]ProblemDetails/api/v1/account/support-agent-invitations/{agentId}/acceptAccept one pending invitation: the caller becomes the application's agent (`status: active`). 404 `support-agent-invitation-not-found` for anything that is not the caller's pending invitation; 409 when the caller is already one of the application's agents.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
agentId | path | string (uuid) | yes | — |
Request body
No request body.
Responses
SupportAgentInvitationDtoProblemDetailsProblemDetailsProblemDetails/api/v1/account/support-agent-invitations/{agentId}/declineDecline one pending invitation: the roster shows it `declined` and nobody is named; only the administrator inviting the address again reopens it. 404 `support-agent-invitation-not-found` for anything that is not the caller's pending invitation — the same single answer as accept.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
agentId | path | string (uuid) | yes | — |
Request body
No request body.
Responses
SupportAgentInvitationDtoProblemDetailsProblemDetailsTakeover
/api/v1/auth/takeover/emergency-freezePlace an emergency credential freeze on the caller's own account and terminate every active session. Idempotent: a repeat call returns the original freeze instant.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
EmergencyFreezeRequestasapplication/*+json,application/json,text/json
Responses
EmergencyFreezeResponseProblemDetailsProblemDetails/api/v1/auth/takeover/emergency-freeze/by-signed-linkPlace an emergency credential freeze authorised by a <b>signed link</b> rather than a session, and discard the in-flight recovery attempt the link names.
`[AllowAnonymous]` (SEC-002, explicit): the reader of an FR-66.114 "this wasn't me → freeze" alert holds no device, no app and no session — that is the definition of the `account-recovery-lost-devices` population, and requiring a bearer token would make this control unexecutable by everyone it exists for. The HMAC over `(accountId . recoverySessionId . expiresAtUnix)` IS the credential. Rate-limited by IP under the platform default policy (SEC-004), which is what bounds signature guessing on an unauthenticated endpoint. A bad signature and an unknown account both answer <b>401</b>, never 404 — the two must be indistinguishable or the endpoint becomes an account-existence oracle for anyone who can POST JSON. An expired link answers <b>410</b>, which is safe to distinguish because it is only ever reached by a link that already proved genuine.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
FreezeBySignedLinkRequestasapplication/*+json,application/json,text/json
Responses
FreezeBySignedLinkResponseProblemDetailsProblemDetails/api/v1/auth/takeover/incidentThe caller's own takeover-recovery state: whether the account is frozen right now, and the open incident if there is one (#7393). The hub renders its step rail from this, so a victim who leaves and comes back resumes instead of being offered the freeze again.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
No request body.
Responses
TakeoverStateViewProblemDetails/api/v1/auth/takeover/incident/{incidentId}/progressRecord a completed step (`keys-rotated`, `shares-revoked`, `closed`) on the caller's own open incident (#7393). An incident id that is not the caller's open incident answers 404 whether it belongs to someone else or to no one.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
incidentId | path | string (uuid) | yes | — |
Request body
Not marked as required in the document.
RecordTakeoverProgressRequestasapplication/*+json,application/json,text/json
Responses
TakeoverStateViewProblemDetailsProblemDetailsProblemDetailsTestTenants
/api/v1/admin/test-tenantsProvisions a verified `@browsertest.essence.digital` test-tenant account with the `TestTenant` role. Platform-admin only.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
CreateTestTenantRequestasapplication/*+json,application/json,text/json
Responses
CreateTestTenantResultProblemDetailsProblemDetailsProblemDetailsVerifiedNameChanges
/api/v1/identity/verified-name-changesOpen a verified-name-change session (records the old/new name hashes).
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
RequestVerifiedNameChangeRequestasapplication/*+json,application/json,text/json
Responses
RequestVerifiedNameChangeResultProblemDetailsProblemDetailsProblemDetails/api/v1/identity/verified-name-changes/{changeId}Read the change session (masked; ZK-safe).
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
changeId | path | string (uuid) | yes | — |
Request body
No request body.
Responses
VerifiedNameChangeViewProblemDetails/api/v1/identity/verified-name-changes/{changeId}/cancelCancel the change before commit (retain the prior verified name).
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
changeId | path | string (uuid) | yes | — |
Request body
No request body.
Responses
CancelVerifiedNameChangeResultProblemDetailsProblemDetails/api/v1/identity/verified-name-changes/{changeId}/commitCommit cutover; broadcasts the ZK-safe verified-name-change event.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
changeId | path | string (uuid) | yes | — |
Request body
Not marked as required in the document.
CommitVerifiedNameChangeRequestasapplication/*+json,application/json,text/json
Responses
CommitVerifiedNameChangeResultProblemDetailsProblemDetailsProblemDetails/api/v1/identity/verified-name-changes/{changeId}/reattestRecord that the new name was re-attested against fresh identity evidence.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
changeId | path | string (uuid) | yes | — |
Request body
Not marked as required in the document.
ReattestVerifiedNameChangeRequestasapplication/*+json,application/json,text/json
Responses
ReattestVerifiedNameChangeResultProblemDetailsProblemDetailsProblemDetailsWebAuthn
/api/v1/auth/webauthn/authenticate/beginBegins a WebAuthn authentication ceremony. Returns credential request options including a challenge for the client to pass to navigator.credentials.get(). Supports both identified (user known) and discoverable (passkey) flows.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
BeginWebAuthnAuthenticationRequestasapplication/*+json,application/json,text/json
Responses
WebAuthnAuthenticationOptions/api/v1/auth/webauthn/authenticate/completeCompletes a WebAuthn authentication ceremony. Verifies the assertion response and issues authentication tokens on success.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
CompleteWebAuthnAuthenticationRequestasapplication/*+json,application/json,text/json
Responses
WebAuthnAuthenticationResultProblemDetails/api/v1/auth/webauthn/credentialsLists the calling user's active passkeys for the Security-settings management surface. Returns an envelope `{ data: [...] }`.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
No request body.
Responses
WebAuthnCredentialListResponseProblemDetails/api/v1/auth/webauthn/credentials/{id}Removes (deactivates) one of the calling user's passkeys.
Requires a fresh (≤ 5 minutes) GPG 44 medium step-up elevation, `act=passkey-removal`, on `X-Step-Up-Token` (Essence.Identity.Auth.Api.Security.IPasskeyRemovalStepUpGate; DVS-4.4, TF 1.0 §7.3.1.c): removing a way to sign in is not something a bearer session alone may do. Checked before the credential is looked up, so a refusal says nothing about which passkeys exist.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | — |
Request body
No request body.
Responses
ProblemDetailsProblemDetails/api/v1/auth/webauthn/credentials/{id}Renames one of the calling user's passkeys.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | — |
Request body
Not marked as required in the document.
RenameWebAuthnCredentialRequestasapplication/*+json,application/json,text/json
Responses
ProblemDetailsProblemDetails/api/v1/auth/webauthn/login/completeCompletes a WebAuthn authentication ceremony. Verifies the assertion response and issues authentication tokens on success.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
CompleteWebAuthnAuthenticationRequestasapplication/*+json,application/json,text/json
Responses
WebAuthnAuthenticationResultProblemDetails/api/v1/auth/webauthn/login/optionsBegins a WebAuthn authentication ceremony. Returns credential request options including a challenge for the client to pass to navigator.credentials.get(). Supports both identified (user known) and discoverable (passkey) flows.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
BeginWebAuthnAuthenticationRequestasapplication/*+json,application/json,text/json
Responses
WebAuthnAuthenticationOptions/api/v1/auth/webauthn/passwordless/challengeIssues a passwordless WebAuthn challenge with an EMPTY `allowCredentials` list so the authenticator picks a discoverable credential (passkey). No username is collected at this step; the user is identified by the `userHandle` the authenticator returns at login time.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
PasswordlessLoginChallengeRequestasapplication/*+json,application/json,text/json
Responses
PasswordlessLoginChallengeResult/api/v1/auth/webauthn/passwordless/loginCompletes a passwordless WebAuthn login by verifying the assertion against the credential identified by the supplied `userHandle`. On success returns full authentication tokens — this is a primary-factor login, no password involved.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
PasswordlessLoginRequestasapplication/*+json,application/json,text/json
Responses
PasswordlessLoginResultProblemDetails/api/v1/auth/webauthn/register/beginBegins a WebAuthn registration ceremony. Returns credential creation options including a challenge for the client to pass to navigator.credentials.create().
Requires a fresh (≤ 5 minutes) `act=authenticator-enrolment` elevation on `X-Step-Up-Token`, proved with a factor the account already has (DVS-4.4b): otherwise a bearer session alone could add its own passkey and then pass every other step-up with it.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
BeginWebAuthnRegistrationRequestasapplication/*+json,application/json,text/json
Responses
WebAuthnRegistrationOptionsProblemDetails/api/v1/auth/webauthn/register/completeCompletes a WebAuthn registration ceremony. Verifies the attestation response from the authenticator and stores the credential.
Requires the same fresh `act=authenticator-enrolment` elevation as `register/begin` (DVS-4.4b), so a ceremony begun with one cannot be finished after it has gone stale.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
CompleteWebAuthnRegistrationRequestasapplication/*+json,application/json,text/json
Responses
WebAuthnRegistrationResultProblemDetailsProblemDetails/api/v1/auth/webauthn/register/optionsBegins a WebAuthn registration ceremony. Returns credential creation options including a challenge for the client to pass to navigator.credentials.create().
Requires a fresh (≤ 5 minutes) `act=authenticator-enrolment` elevation on `X-Step-Up-Token`, proved with a factor the account already has (DVS-4.4b): otherwise a bearer session alone could add its own passkey and then pass every other step-up with it.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
BeginWebAuthnRegistrationRequestasapplication/*+json,application/json,text/json
Responses
WebAuthnRegistrationOptionsProblemDetails/api/v1/webauthn/authenticate/beginBegins a WebAuthn authentication ceremony. Returns credential request options including a challenge for the client to pass to navigator.credentials.get(). Supports both identified (user known) and discoverable (passkey) flows.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
BeginWebAuthnAuthenticationRequestasapplication/*+json,application/json,text/json
Responses
WebAuthnAuthenticationOptions/api/v1/webauthn/authenticate/completeCompletes a WebAuthn authentication ceremony. Verifies the assertion response and issues authentication tokens on success.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
CompleteWebAuthnAuthenticationRequestasapplication/*+json,application/json,text/json
Responses
WebAuthnAuthenticationResultProblemDetails/api/v1/webauthn/credentialsLists the calling user's active passkeys for the Security-settings management surface. Returns an envelope `{ data: [...] }`.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
No request body.
Responses
WebAuthnCredentialListResponseProblemDetails/api/v1/webauthn/credentials/{id}Removes (deactivates) one of the calling user's passkeys.
Requires a fresh (≤ 5 minutes) GPG 44 medium step-up elevation, `act=passkey-removal`, on `X-Step-Up-Token` (Essence.Identity.Auth.Api.Security.IPasskeyRemovalStepUpGate; DVS-4.4, TF 1.0 §7.3.1.c): removing a way to sign in is not something a bearer session alone may do. Checked before the credential is looked up, so a refusal says nothing about which passkeys exist.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | — |
Request body
No request body.
Responses
ProblemDetailsProblemDetails/api/v1/webauthn/credentials/{id}Renames one of the calling user's passkeys.
Authentication:Bearer (the document-wide requirement)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | — |
Request body
Not marked as required in the document.
RenameWebAuthnCredentialRequestasapplication/*+json,application/json,text/json
Responses
ProblemDetailsProblemDetails/api/v1/webauthn/login/completeCompletes a WebAuthn authentication ceremony. Verifies the assertion response and issues authentication tokens on success.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
CompleteWebAuthnAuthenticationRequestasapplication/*+json,application/json,text/json
Responses
WebAuthnAuthenticationResultProblemDetails/api/v1/webauthn/login/optionsBegins a WebAuthn authentication ceremony. Returns credential request options including a challenge for the client to pass to navigator.credentials.get(). Supports both identified (user known) and discoverable (passkey) flows.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
BeginWebAuthnAuthenticationRequestasapplication/*+json,application/json,text/json
Responses
WebAuthnAuthenticationOptions/api/v1/webauthn/passwordless/challengeIssues a passwordless WebAuthn challenge with an EMPTY `allowCredentials` list so the authenticator picks a discoverable credential (passkey). No username is collected at this step; the user is identified by the `userHandle` the authenticator returns at login time.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
PasswordlessLoginChallengeRequestasapplication/*+json,application/json,text/json
Responses
PasswordlessLoginChallengeResult/api/v1/webauthn/passwordless/loginCompletes a passwordless WebAuthn login by verifying the assertion against the credential identified by the supplied `userHandle`. On success returns full authentication tokens — this is a primary-factor login, no password involved.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
PasswordlessLoginRequestasapplication/*+json,application/json,text/json
Responses
PasswordlessLoginResultProblemDetails/api/v1/webauthn/register/beginBegins a WebAuthn registration ceremony. Returns credential creation options including a challenge for the client to pass to navigator.credentials.create().
Requires a fresh (≤ 5 minutes) `act=authenticator-enrolment` elevation on `X-Step-Up-Token`, proved with a factor the account already has (DVS-4.4b): otherwise a bearer session alone could add its own passkey and then pass every other step-up with it.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
BeginWebAuthnRegistrationRequestasapplication/*+json,application/json,text/json
Responses
WebAuthnRegistrationOptionsProblemDetails/api/v1/webauthn/register/completeCompletes a WebAuthn registration ceremony. Verifies the attestation response from the authenticator and stores the credential.
Requires the same fresh `act=authenticator-enrolment` elevation as `register/begin` (DVS-4.4b), so a ceremony begun with one cannot be finished after it has gone stale.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
CompleteWebAuthnRegistrationRequestasapplication/*+json,application/json,text/json
Responses
WebAuthnRegistrationResultProblemDetailsProblemDetails/api/v1/webauthn/register/optionsBegins a WebAuthn registration ceremony. Returns credential creation options including a challenge for the client to pass to navigator.credentials.create().
Requires a fresh (≤ 5 minutes) `act=authenticator-enrolment` elevation on `X-Step-Up-Token`, proved with a factor the account already has (DVS-4.4b): otherwise a bearer session alone could add its own passkey and then pass every other step-up with it.
Authentication:Bearer (the document-wide requirement)
Parameters
Takes no parameters.
Request body
Not marked as required in the document.
BeginWebAuthnRegistrationRequestasapplication/*+json,application/json,text/json
Responses
WebAuthnRegistrationOptionsProblemDetailsSchemas
AcceptInvitationAsMemberResult
| Property | Type | Required | Description |
|---|---|---|---|
accessToken | string | null | no | — |
accessTokenExpiresAt | string (date-time) | no | — |
invitationId | string (uuid) | no | — |
organizationId | string (uuid) | no | — |
sponsoredEntitlementGranted | boolean | no | — |
AcceptInvitationCommand
| Property | Type | Required | Description |
|---|---|---|---|
deviceFingerprint | string | null | no | — |
deviceType | string | null | no | — |
firstName | string | null | no | — |
ipAddress | string | null | no | — |
lastName | string | null | no | — |
passwordHash | string | null | no | — |
token | string | null | no | — |
userAgent | string | null | no | — |
AcceptInvitationResult
| Property | Type | Required | Description |
|---|---|---|---|
accessToken | string | null | no | — |
accessTokenExpiresAt | string (date-time) | no | — |
homeRegion | string | null | no | — |
organizationId | string (uuid) | no | — |
refreshToken | string | null | no | — |
refreshTokenExpiresAt | string (date-time) | no | — |
sponsoredEntitlementGranted | boolean | no | — |
userId | string (uuid) | no | — |
AccountActionNoticeDto
| Property | Type | Required | Description |
|---|---|---|---|
action | string | null | no | — |
actionId | string (uuid) | no | — |
appealCaseRef | string | null | no | — |
appealable | boolean | no | — |
duration | string | null | no | — |
effectiveAt | string (date-time) | no | — |
policyClause | string | null | no | — |
reasonCategory | string | null | no | — |
scope | string | null | no | — |
status | string | null | no | — |
AccountClosureCancelRequest
The two values the closure alert's link carries.
| Property | Type | Required | Description |
|---|---|---|---|
closureId | string (uuid) | no | The closure (the closure event's id). |
token | string | null | no | The link's single-use token. |
AccountClosureCancelResponse
A live link was used: the closure is cancelled and the account is open.
| Property | Type | Required | Description |
|---|---|---|---|
cancelled | boolean | no | — |
AccountClosureDecisionResult
| Property | Type | Required | Description |
|---|---|---|---|
accountId | string (uuid) | no | — |
appealRoute | string | null | no | — |
approvedAt | string (date-time) | null | no | — |
approvedBy | string (uuid) | null | no | — |
cause | string | null | no | — |
closureEventId | string (uuid) | null | no | — |
decidedAt | string (date-time) | null | no | — |
decidedBy | string (uuid) | null | no | — |
decisionId | string (uuid) | no | — |
evidenceReference | string | null | no | — |
openedAt | string (date-time) | no | — |
reasonCategory | string | null | no | — |
reference | string | null | no | — |
rejectedAt | string (date-time) | null | no | — |
rejectedBy | string (uuid) | null | no | — |
shredNotBefore | string (date-time) | null | no | — |
status | string | null | no | — |
AccountFactorHoldView
A hold on the caller's text-message factor, as the holder sees it. No number, ids and instants only.
| Property | Type | Required | Description |
|---|---|---|---|
canConfirmHere | boolean | no | Whether this session may end it now. |
event | string | null | no | The change the operator attested: `sim_swap`, `esim_reprovision`, `port_out` or `port_in`. |
factor | string | null | no | `sms`. |
heldUntil | string (date-time) | no | When it lapses unless ended earlier (UTC). |
holdId | string (uuid) | no | The hold. |
placedAt | string (date-time) | no | When it came into force (UTC). |
releasePath | string | null | no | How it ended, if it has. |
releasePaths | string[] | null | no | How it can end. |
releasedAt | string (date-time) | null | no | When it ended (UTC), if it has. |
AccountMergeGovernanceResult
| Property | Type | Required | Description |
|---|---|---|---|
mode | string | null | no | — |
orgName | string | null | no | — |
reason | string | null | no | — |
resolution | string | null | no | — |
AccountMergeReversibilityResult
| Property | Type | Required | Description |
|---|---|---|---|
posture | string | null | no | — |
windowDays | integer (int32) | null | no | — |
AccountMergeStatusResult
| Property | Type | Required | Description |
|---|---|---|---|
committedAt | string (date-time) | null | no | — |
mergeSessionId | string (uuid) | no | — |
reversedAt | string (date-time) | null | no | — |
reversibleUntil | string (date-time) | null | no | — |
stages | MergeStageProgressDto[] | null | no | — |
status | string | null | no | — |
ActingAsContextDto
| Property | Type | Required | Description |
|---|---|---|---|
capabilities | string[] | null | no | — |
delegationId | string (uuid) | no | — |
expiresAt | string (date-time) | null | no | — |
grantId | string (uuid) | no | — |
isActive | boolean | no | — |
principalUserId | string (uuid) | no | — |
revokedAt | string (date-time) | null | no | — |
surface | string | null | no | — |
ActiveDeviceSummary
| Property | Type | Required | Description |
|---|---|---|---|
deviceId | string (uuid) | no | — |
deviceType | string | null | no | — |
lastUsedAt | string (date-time) | null | no | — |
name | string | null | no | — |
ActiveProbateRoleResult
| Property | Type | Required | Description |
|---|---|---|---|
grantId | string (uuid) | null | no | — |
hasActiveGrant | boolean | no | — |
AddExecutorOfficerRequest
Request body for adding an individual to the executor roster.
| Property | Type | Required | Description |
|---|---|---|---|
officerReference | string | null | no | Optional opaque, org-chosen, non-PII reference (e.g. a staff number). |
officerUserId | string (uuid) | no | The officer's user-principal id. |
AdminUserPageDto
| Property | Type | Required | Description |
|---|---|---|---|
items | AdminUserSummaryDto[] | null | no | — |
page | integer (int32) | no | — |
pageSize | integer (int32) | no | — |
totalCount | integer (int32) | no | — |
AdminUserSummaryDto
| Property | Type | Required | Description |
|---|---|---|---|
administrativeStatus | string | null | no | — |
createdAt | string (date-time) | no | — |
currentAccountActionId | string (uuid) | null | no | — |
email | string | null | no | — |
emailVerified | boolean | no | — |
failedLoginAttempts | integer (int32) | no | — |
firstName | string | null | no | — |
homeRegion | string | null | no | — |
isActive | boolean | no | — |
lastLoginAt | string (date-time) | null | no | — |
lastName | string | null | no | — |
lockoutEndAt | string (date-time) | null | no | — |
mfaEnabled | boolean | no | — |
phoneVerified | boolean | no | — |
preferredLocale | string | null | no | — |
roles | string[] | null | no | — |
userId | string (uuid) | no | — |
AdviceAgencyRow
| Property | Type | Required | Description |
|---|---|---|---|
adviserCapabilities | string[] | null | no | — |
agencyId | string (uuid) | no | — |
agencyName | string | null | no | — |
isRecognised | boolean | no | — |
organizationId | string (uuid) | no | — |
recognisedAt | string (date-time) | no | — |
regulatoryBody | string | null | no | — |
regulatoryReference | string | null | no | — |
status | string | null | no | — |
statusChangedAt | string (date-time) | no | — |
statusReason | string | null | no | — |
AdviserCaseAssignmentRow
| Property | Type | Required | Description |
|---|---|---|---|
adviserUserId | string (uuid) | no | — |
assignedAt | string (date-time) | no | — |
assignedByUserId | string (uuid) | no | — |
assignmentId | string (uuid) | no | — |
caseReference | string | null | no | — |
clientUserId | string (uuid) | no | — |
endReason | string | null | no | — |
endedAt | string (date-time) | null | no | — |
endedByUserId | string (uuid) | null | no | — |
isLive | boolean | no | — |
reassignedToAdviserUserId | string (uuid) | null | no | — |
status | string | null | no | — |
AdviserCaseloadResult
| Property | Type | Required | Description |
|---|---|---|---|
agencyId | string (uuid) | no | — |
assignments | AdviserCaseAssignmentRow[] | null | no | — |
liveCount | integer (int32) | no | — |
totalCount | integer (int32) | no | — |
AgentKeyResponse
Result of registering an agent key.
| Property | Type | Required | Description |
|---|---|---|---|
agentReference | string | null | no | The agent. |
replaced | boolean | no | True when an earlier key was replaced. |
thumbprint | string | null | no | RFC 7638 thumbprint — the `cnf.jkt` the agent's tokens now carry. |
AgentPublicJwkRequest
Body of `PUT …/{agentReference}/key`: one EC P-256 public JWK. Every member other than the four declared lands in Essence.Identity.Auth.Api.Controllers.AgentPublicJwkRequest.AdditionalMembers so it can be refused by name.
| Property | Type | Required | Description |
|---|---|---|---|
crv | string | null | no | Curve — must be `P-256`. |
kty | string | null | no | Key type — must be `EC`. |
x | string | null | no | x coordinate, base64url. |
y | string | null | no | y coordinate, base64url. |
AgentTokenRequest
Request body for an agent token exchange.
| Property | Type | Required | Description |
|---|---|---|---|
agentReference | string | null | no | The agent's opaque reference. |
secret | string | null | no | The credential secret. |
AgentTokenResponse
An issued agent session.
| Property | Type | Required | Description |
|---|---|---|---|
expiresAt | string (date-time) | no | When it expires (the token's `exp`). |
sessionToken | string | null | no | The agent access token — a platform JWT since AG-D1 (it was an opaque secret before). The field keeps its name so existing callers need no change. |
tokenType | string | null | no | How to present Essence.Identity.Auth.Api.Controllers.AgentTokenResponse.SessionToken: always `Bearer` (CONTRACTS §2). |
AnswerOutOfBandProofChallengeResult
| Property | Type | Required | Description |
|---|---|---|---|
attemptsRemaining | integer (int32) | no | — |
challengeId | string (uuid) | no | — |
outcome | OutOfBandProofOutcome | no | — |
proven | boolean | no | — |
AnswerProofChallengeRequest
Answer request.
| Property | Type | Required | Description |
|---|---|---|---|
code | string | null | no | The one-time code as delivered to the account's own recovery address. |
AppealCaseDto
| Property | Type | Required | Description |
|---|---|---|---|
caseRef | string | null | no | — |
expectedResponseBy | string (date-time) | no | — |
status | string | null | no | — |
submittedAt | string (date-time) | no | — |
ApplyAccountActionRequest
Body for `POST /api/v1/account/actions` (the EPIC 48 moderation decision). The operator id is NOT accepted here — it is stamped server-side from the authenticated principal for un-spoofable due-process attribution.
| Property | Type | Required | Description |
|---|---|---|---|
action | string | null | no | Wire token of the graduated action (`warn`…`reinstate`…`dismiss`). |
duration | string | null | no | Optional human/token duration for a time-boxed action. |
policyClause | string | null | no | Policy / ToS clause the action is anchored to (mandatory). |
reasonCategory | string | null | no | Category-level reason disclosed to the user (mandatory). |
reasonInternalRef | string | null | no | Opaque pointer to the operator's internal notes; never the note text. |
reportId | string (uuid) | null | no | Originating abuse-report id, when the action came from a triaged report. |
scope | string | null | no | Scope token (`account` or a capability); defaults to `account`. |
targetUserId | string (uuid) | no | The end-user account the action targets. |
ApplyAccountActionResult
| Property | Type | Required | Description |
|---|---|---|---|
actionId | string (uuid) | no | — |
appealable | boolean | no | — |
status | string | null | no | — |
AssignAdviserToCaseRequest
Request body for assigning an adviser to a client's case.
| Property | Type | Required | Description |
|---|---|---|---|
adviserUserId | string (uuid) | no | The adviser taking the case. |
caseReference | string | null | no | The agency's own opaque case reference. |
clientUserId | string (uuid) | no | The client whose case it is. |
AssistActionDto
| Property | Type | Required | Description |
|---|---|---|---|
actionId | string (uuid) | no | — |
actionType | string | null | no | — |
assistantUserId | string (uuid) | no | — |
occurredAt | string (date-time) | no | — |
sessionId | string (uuid) | no | — |
targetRef | string | null | no | — |
touchedKeyMaterial | boolean | no | — |
AssistedRecoveryRequestBody
Request body for a delegated assisted-recovery request.
| Property | Type | Required | Description |
|---|---|---|---|
context | string | null | no | Optional non-PII free-text hint to help the helpdesk verify the subject. |
reason | string | null | no | Why self-service is impossible — `lost-mfa` | `locked`. Optional: omitted or blank defaults to `locked`. Any OTHER value is refused `400` rather than defaulted, because a reason the subject stated and a reason they did not state are different facts and the helpdesk agent reading the case cannot tell them apart afterwards (#8916). |
workEmail | string | null | no | The subject's work email — routing key into their org helpdesk queue. |
AssistedRecoveryRequestResponse
Response for an accepted assisted-recovery request.
| Property | Type | Required | Description |
|---|---|---|---|
requestRef | string | null | no | The opaque request reference the subject can quote to their helpdesk. |
AssistedRecoveryStatusResponse
Subject-facing status of a delegated assisted-recovery case (journey step 1b). Metadata only — see M:Essence.Identity.Auth.Api.Controllers.AssistedRecoveryController.GetStatus(System.Guid,System.Threading.CancellationToken).
| Property | Type | Required | Description |
|---|---|---|---|
canComplete | boolean | no | True when the subject may redeem their recovery token now. |
decidedAt | string (date-time) | null | no | UTC instant the case was decided or completed; null while queued. |
decisionReason | string | null | no | Machine reason slug when rejected; null otherwise. |
initiatedAt | string (date-time) | no | UTC instant the request was raised. |
reason | string | null | no | The subject's own stated reason (`lost-mfa` | `locked`). |
requestRef | string | null | no | Echo of the reference queried. |
status | string | null | no | `queued` | `authorised` | `rejected` | `completed` | `withdrawn`. |
AssurancePostureResult
| Property | Type | Required | Description |
|---|---|---|---|
attestedAt | string (date-time) | null | no | — |
attestedBy | string | null | no | — |
level | string | null | no | — |
verified | boolean | no | — |
AssuranceRecordResult
| Property | Type | Required | Description |
|---|---|---|---|
auditAnchorReference | string | null | no | — |
authority | string | null | no | — |
canProceed | boolean | no | — |
lastProvenance | string | null | no | — |
level | string | null | no | — |
levelRecordedAt | string (date-time) | no | — |
proofingCompleted | boolean | no | — |
proofingDisposition | string | null | no | — |
proofingPolicy | string | null | no | — |
recoveryDecisionRecordedAt | string (date-time) | null | no | — |
recoveryDisposition | string | null | no | — |
subjectUserId | string (uuid) | no | — |
validUntil | string (date-time) | null | no | — |
AttestContactFieldRequest
Request body for recording a contact-field provenance attestation.
| Property | Type | Required | Description |
|---|---|---|---|
assurance | string | null | no | `self_asserted | verified | attested`. |
fieldKey | string | null | no | — |
signingKeyId | string | null | no | — |
AttestProfessionalCredentialRequest
Request body for recording a professional-credential attestation.
| Property | Type | Required | Description |
|---|---|---|---|
assurance | string | null | no | `self_asserted | verified | attested`. |
body | string | null | no | — |
credentialType | string | null | no | — |
expiresAt | string (date-time) | null | no | — |
fieldKey | string | null | no | — |
signingKeyId | string | null | no | — |
BackfillSetupPostureRequest
Request body for the setup-posture backfill.
| Property | Type | Required | Description |
|---|---|---|---|
afterId | string (uuid) | null | no | Keyset cursor — process accounts with an id strictly greater than this. Omit to start at the beginning; pass back the previous call's `nextAfterId` to continue. |
batchSize | integer (int32) | null | no | Accounts per call. Clamped to Essence.Identity.Auth.Application.Commands.BackfillSetupPostureCommand.MaxBatchSize; a hard ceiling rather than a validation error, so a fat-fingered page size cannot move the whole table in one request. |
dryRun | boolean | no | When true, count the match set and publish nothing. |
BackfillSetupPostureResult
| Property | Type | Required | Description |
|---|---|---|---|
announced | integer (int32) | no | — |
complete | boolean | no | — |
custodial | integer (int32) | no | — |
examined | integer (int32) | no | — |
instantStamped | integer (int32) | no | — |
nextAfterId | string (uuid) | null | no | — |
totalAccounts | integer (int32) | no | — |
verified | integer (int32) | no | — |
BeginWebAuthnAuthenticationRequest
| Property | Type | Required | Description |
|---|---|---|---|
userId | string (uuid) | null | no | — |
userVerification | string | null | no | — |
BeginWebAuthnRegistrationRequest
| Property | Type | Required | Description |
|---|---|---|---|
authenticatorAttachment | string | null | no | — |
requireResidentKey | boolean | null | no | Nullable so the controller can distinguish "caller didn't send this" (→ defaults to TRUE, discoverable/passkey) from an explicit `false` opt-out. A plain `bool` here previously defaulted to `false` on every request that omitted the field — which was every FE call site — silently registering non-discoverable credentials that the usernameless passkey login could never find. |
userVerification | string | null | no | — |
BillingProfileDto
| Property | Type | Required | Description |
|---|---|---|---|
displayName | string | null | no | — |
email | string | null | no | — |
exists | boolean | no | — |
userId | string (uuid) | no | — |
BiometricReenrolmentOversightResult
| Property | Type | Required | Description |
|---|---|---|---|
organizationId | string (uuid) | no | — |
rows | BiometricReenrolmentOversightRow[] | null | no | — |
stalledCount | integer (int32) | no | — |
totalCount | integer (int32) | no | — |
BiometricReenrolmentOversightRow
| Property | Type | Required | Description |
|---|---|---|---|
currentStep | string | null | no | — |
detectedAt | string (date-time) | no | — |
elapsedMinutes | integer (int32) | no | — |
memberRef | string | null | no | — |
status | string | null | no | — |
BiometricReenrolmentResult
| Property | Type | Required | Description |
|---|---|---|---|
assuranceRef | string | null | no | — |
currentStep | string | null | no | — |
detectedAt | string (date-time) | no | — |
lockoutState | string | null | no | — |
mismatchReason | string | null | no | — |
reestablishAction | string | null | no | — |
sessionId | string (uuid) | no | — |
status | string | null | no | — |
BlockDeviceRequest
| Property | Type | Required | Description |
|---|---|---|---|
reason | string | null | no | — |
BlockDeviceResult
| Property | Type | Required | Description |
|---|---|---|---|
message | string | null | no | — |
success | boolean | no | — |
BootstrapReturningNationalRequest
Request body for a returning-national bootstrap. It carries no origin jurisdiction, scheme or foreign LoA: those are read from the caller's own intake (#14018), and any such field a client still sends is ignored.
| Property | Type | Required | Description |
|---|---|---|---|
matchedPriorSovereignVaultRef | string | null | no | — |
residualCheckSatisfied | boolean | no | — |
CancelPrimaryContactChangeResult
| Property | Type | Required | Description |
|---|---|---|---|
cancelledAt | string (date-time) | no | — |
changeId | string (uuid) | no | — |
status | string | null | no | — |
CancelVerifiedNameChangeResult
| Property | Type | Required | Description |
|---|---|---|---|
cancelledAt | string (date-time) | no | — |
changeId | string (uuid) | no | — |
status | string | null | no | — |
ChangeAdviceAgencyStandingRequest
Request body for changing an agency's recognition standing.
| Property | Type | Required | Description |
|---|---|---|---|
action | string | null | no | One of `suspend`, `restore`, `withdraw`. |
reason | string | null | no | Required for `suspend` and `withdraw`. |
ChangePasswordRequest
Request body for `POST /password/change`. Both fields are client-derived PBKDF2 hashes — never plaintext passwords.
| Property | Type | Required | Description |
|---|---|---|---|
breachCheck | string | null | no | The client's breached-password check of the new password (DVS-4.7): `"passed"`, `"not_performed"`, or absent (recorded as `not_reported`). An honest-client fact. |
currentPasswordHash | string | null | no | — |
newPasswordHash | string | null | no | — |
passwordPolicyVersion | integer (int32) | null | no | The client password-policy version (DVS-4.7); optional. |
ChangePasswordResult
| Property | Type | Required | Description |
|---|---|---|---|
errorMessage | string | null | no | — |
sessionsRevoked | integer (int32) | no | — |
success | boolean | no | — |
ChangeProfessionalAdviserStandingRequest
Request body for changing an adviser's standing.
| Property | Type | Required | Description |
|---|---|---|---|
action | string | null | no | One of `suspend`, `reinstate`, `revoke`. |
reason | string | null | no | Required for `suspend` and `revoke`. |
ChangeSafeguardingAuthorityStandingRequest
Request body for changing a body's recognition standing.
| Property | Type | Required | Description |
|---|---|---|---|
action | string | null | no | One of `suspend`, `restore`, `withdraw`. |
reason | string | null | no | Required for `suspend` and `withdraw`. |
ChangeSafeguardingOfficerStandingRequest
Request body for changing an officer's standing.
| Property | Type | Required | Description |
|---|---|---|---|
action | string | null | no | One of `suspend`, `reinstate`, `revoke`. |
reason | string | null | no | Required for `suspend` and `revoke`. |
ClaimVaultContextDto
| Property | Type | Required | Description |
|---|---|---|---|
alreadyClaimed | boolean | no | — |
requiredAssurance | string | null | no | — |
status | string | null | no | — |
subjectId | string (uuid) | no | — |
whatChanges | string[] | null | no | — |
whatYouKeep | string[] | null | no | — |
CoAuthoriserDirectoryEntry
| Property | Type | Required | Description |
|---|---|---|---|
authorisedSince | string (date-time) | no | — |
authorityId | string (uuid) | no | — |
authorityName | string | null | no | — |
officerReference | string | null | no | — |
officerUserId | string (uuid) | no | — |
verificationLevel | string | null | no | — |
CoAuthoriserDirectoryResult
| Property | Type | Required | Description |
|---|---|---|---|
officers | CoAuthoriserDirectoryEntry[] | null | no | — |
totalCount | integer (int32) | no | — |
CommitAccountMergeRequest
Wire body to commit a merge. The destructive confirm requires Essence.Identity.Auth.Api.Controllers.CommitAccountMergeRequest.AcknowledgeRetirement and a fresh survivor Essence.Identity.Auth.Api.Controllers.CommitAccountMergeRequest.StepUp (WCAG 2.2 SC 3.3.4, debt-2026-07-03-226); grant references stay optional.
| Property | Type | Required | Description |
|---|---|---|---|
acknowledgeRetirement | boolean | no | The survivor's affirmative acknowledgement that the folded account is retired. |
droppedGrantRefs | string[] | null | no | Grants not carried over — they end with the retired account (debt-2026-08-10-005). |
policyDecision | MergePolicyDecisionInput | no | — |
reconfirmRequiredGrantRefs | string[] | null | no | — |
repointedGrantRefs | string[] | null | no | — |
stepUp | MergeStepUpDto | no | — |
suspendedGrantRefs | string[] | null | no | Regulated grants suspended pending re-confirmation (debt-2026-08-10-005). |
CommitAccountMergeResponse
| Property | Type | Required | Description |
|---|---|---|---|
auditRef | string | null | no | The EPIC 4 / 12 audit anchor reference for this merge (debt-2026-08-10-005) — the same value carried on `AccountMergedIntegrationEvent`, so the member's receipt and the organisation's projection quote one anchor for one merge. |
mergeSessionId | string (uuid) | no | — |
mergedAt | string (date-time) | no | — |
reversibleUntil | string (date-time) | no | — |
status | string | null | no | — |
CommitPrimaryContactChangeResult
| Property | Type | Required | Description |
|---|---|---|---|
changeId | string (uuid) | no | — |
committedAt | string (date-time) | no | — |
status | string | null | no | — |
CommitVerifiedNameChangeRequest
Wire body to commit the change (the EPIC 6 recipient split).
| Property | Type | Required | Description |
|---|---|---|---|
notifiedCount | integer (int32) | no | — |
withheldCount | integer (int32) | no | — |
CommitVerifiedNameChangeResult
| Property | Type | Required | Description |
|---|---|---|---|
changeId | string (uuid) | no | — |
committedAt | string (date-time) | no | — |
notifiedCount | integer (int32) | no | — |
status | string | null | no | — |
withheldCount | integer (int32) | no | — |
CommunityVouchedAccount
| Property | Type | Required | Description |
|---|---|---|---|
auditAnchorReference | string | null | no | — |
level | string | null | no | — |
levelRecordedAt | string (date-time) | no | — |
posture | CommunityVouchedPosture | no | — |
provenance | string | null | no | — |
subjectUserId | string (uuid) | no | — |
validUntil | string (date-time) | null | no | — |
CommunityVouchedAccountsResult
| Property | Type | Required | Description |
|---|---|---|---|
accounts | CommunityVouchedAccount[] | null | no | — |
expiringWithinDays | integer (int32) | no | — |
truncated | boolean | no | — |
CommunityVouchedPosture
0 | 1 | 2 with no declared properties.
CompleteAssistedRecoveryBody
Request body for completing a delegated assisted recovery (journey step 4).
| Property | Type | Required | Description |
|---|---|---|---|
newPasswordHash | string | null | no | The <b>client-derived</b> hash of the subject's new credential. Plaintext credentials never reach this service (zero-knowledge). |
recoveryToken | string | null | no | The opaque, single-use CC-061 authorise-only recovery-token reference the subject holds. A lookup handle bound to them — never key material. |
CompleteAssistedRecoveryResponse
Response for a completed assisted recovery.
| Property | Type | Required | Description |
|---|---|---|---|
completed | boolean | no | True when the credential was set and the case closed. |
mfaReenrolmentRequired | boolean | no | True when a lost second factor was cleared and the subject must re-enrol MFA after signing in. |
CompleteMfaLoginCommand
| Property | Type | Required | Description |
|---|---|---|---|
challengeToken | string | null | no | — |
code | string | null | no | — |
ipAddress | string | null | no | — |
method | MfaMethod | no | — |
rememberDevice | boolean | null | no | — |
userAgent | string | null | no | — |
CompleteProofingRequest
Body for recording a subject-reported proofing outcome.
| Property | Type | Required | Description |
|---|---|---|---|
failureReason | string | null | no | Short, non-PII failure reason when Essence.Identity.Auth.Api.Controllers.CompleteProofingRequest.Succeeded is false. |
succeeded | boolean | no | Defaults to `false` (fail closed). Sending `true` on the subject endpoint is refused with 403 — a success must be adjudicated by the proofing provider, not asserted by the subject. |
CompleteWebAuthnAuthenticationRequest
| Property | Type | Required | Description |
|---|---|---|---|
authenticatorData | string | null | no | — |
clientDataJson | string | null | no | — |
credentialId | string | null | no | — |
deviceFingerprint | string | null | no | The browser's device fingerprint, as its password sign-in sends it (#17966). |
deviceType | string | null | no | A `DeviceType` name; used only when the fingerprint registers a new device. |
sessionId | string | null | no | — |
signature | string | null | no | — |
userHandle | string | null | no | — |
CompleteWebAuthnRegistrationRequest
| Property | Type | Required | Description |
|---|---|---|---|
attestationObject | string | null | no | — |
clientDataJson | string | null | no | — |
deviceName | string | null | no | — |
sessionId | string | null | no | — |
transports | string[] | null | no | — |
ConfirmPhoneVerificationRequest
Body of `POST /api/v1/auth/phone/verification/confirm`.
| Property | Type | Required | Description |
|---|---|---|---|
code | string | null | no | — |
ConsentToAssistRequest
Wire body for recording consent-to-assist.
| Property | Type | Required | Description |
|---|---|---|---|
assistantUserId | string (uuid) | no | — |
assistedUserId | string (uuid) | null | no | The assisted owner. Must be the authenticated caller when supplied (a mismatch is rejected with 403); omit it and the caller is used. Retained so an existing client that sends its own id keeps working — it is no longer a way to name somebody else. |
authorityBasis | string | null | no | — |
expiresAt | string (date-time) | null | no | — |
scope | string | null | no | — |
sessionId | string (uuid) | no | — |
ConsentToAssistResponse
Response body for the consent call.
| Property | Type | Required | Description |
|---|---|---|---|
alreadyExisted | boolean | no | — |
grantId | string (uuid) | no | — |
sessionId | string (uuid) | no | — |
ContactFieldAttestationDto
| Property | Type | Required | Description |
|---|---|---|---|
assurance | string | null | no | — |
fieldKey | string | null | no | — |
signingKeyId | string | null | no | — |
status | string | null | no | — |
ContinueAfterDeviceLimitCommand
| Property | Type | Required | Description |
|---|---|---|---|
challengeToken | string | null | no | — |
ipAddress | string | null | no | — |
signOutDeviceIds | (string (uuid))[] | null | no | — |
userAgent | string | null | no | — |
CreateTestTenantRequest
Request body for M:Essence.Identity.Auth.Api.Controllers.TestTenantsController.CreateTestTenant(Essence.Identity.Auth.Api.Controllers.CreateTestTenantRequest).
| Property | Type | Required | Description |
|---|---|---|---|
email | string | null | no | — |
homeRegion | string | null | no | — |
passwordHash | string | null | no | — |
CreateTestTenantResult
| Property | Type | Required | Description |
|---|---|---|---|
userId | string (uuid) | no | — |
CustodialEvidenceResult
| Property | Type | Required | Description |
|---|---|---|---|
code | string | null | no | — |
label | string | null | no | — |
note | string | null | no | — |
required | boolean | no | — |
CustodialInstrumentResult
| Property | Type | Required | Description |
|---|---|---|---|
code | string | null | no | — |
label | string | null | no | — |
note | string | null | no | — |
CustodialOrderResult
| Property | Type | Required | Description |
|---|---|---|---|
decidedAtIso | string | null | no | — |
decisionAuthorityReference | string | null | no | — |
decisionProvenance | string | null | no | — |
grantedRights | string[] | null | no | — |
identityProvisioned | boolean | no | — |
instrumentCode | string | null | no | — |
instrumentLabel | string | null | no | — |
jurisdictionCode | string | null | no | — |
orderProofId | string | null | no | — |
remediation | string | null | no | — |
status | string | null | no | — |
submittedAtIso | string | null | no | — |
CustodialPolicyResult
| Property | Type | Required | Description |
|---|---|---|---|
acceptedInstruments | CustodialInstrumentResult[] | null | no | — |
authoriserRole | string | null | no | — |
jurisdiction | string | null | no | — |
jurisdictionLabel | string | null | no | — |
minimumAssurance | string | null | no | — |
requiredEvidence | CustodialEvidenceResult[] | null | no | — |
source | string | null | no | — |
DeactivateUserResult
| Property | Type | Required | Description |
|---|---|---|---|
cancelBy | string (date-time) | null | no | — |
message | string | null | no | — |
shredNotBefore | string (date-time) | null | no | — |
success | boolean | no | — |
DecideCustodialOrderRequest
The named authoriser's decision on a pending order.
| Property | Type | Required | Description |
|---|---|---|---|
decidedByRef | string | null | no | The external authority's own reference for its decision (their case or order reference). |
remediation | string | null | no | Required on refusal: what the custodian must do next. |
verified | boolean | no | — |
DecideFraudClosureRequest
Body of `POST account-closure-decisions/fraud`. The decider is the caller, never a body field.
| Property | Type | Required | Description |
|---|---|---|---|
accountId | string (uuid) | no | The account to close. |
evidenceReference | string | null | no | The fraud case reference — never the evidence. |
reasonCategory | string | null | no | `fraudulent-creation`, `synthetic-identity` or `terms-breach-unresolved-after-appeal`. |
DeclareOperatingJurisdictionRequest
Body of `PUT /api/v1/sessions/current/operating-jurisdiction`.
| Property | Type | Required | Description |
|---|---|---|---|
jurisdiction | string | null | no | ISO 3166-1 alpha-2 code of the jurisdiction the caller is working from. |
DeclineInvitationCommand
| Property | Type | Required | Description |
|---|---|---|---|
token | string | null | no | — |
DeclineInvitationResult
| Property | Type | Required | Description |
|---|---|---|---|
declined | boolean | no | — |
invitationId | string (uuid) | no | — |
DeclineSupportAccessRequestBody
Request body for declining a held support-access request (#21869).
| Property | Type | Required | Description |
|---|---|---|---|
reasonCode | string | null | no | — |
DelegateAccessGrantCreatedResponse
Response body for the grant call.
| Property | Type | Required | Description |
|---|---|---|---|
alreadyExisted | boolean | no | — |
grantId | string (uuid) | no | — |
DelegateAccessGrantDto
| Property | Type | Required | Description |
|---|---|---|---|
authorityBasis | string | null | no | — |
capabilities | string[] | null | no | — |
delegateUserId | string (uuid) | no | — |
delegationId | string (uuid) | no | — |
expiresAt | string (date-time) | null | no | — |
grantId | string (uuid) | no | — |
principalUserId | string (uuid) | no | — |
revokedAt | string (date-time) | null | no | — |
status | DelegateAccessStatus | no | — |
surface | string | null | no | — |
DelegateAccessStatus
0 | 1 | 2 with no declared properties.
DelegatedAgentDto
| Property | Type | Required | Description |
|---|---|---|---|
agentId | string (uuid) | no | — |
agentReference | string | null | no | — |
createdAt | string (date-time) | no | — |
grantedScopes | string[] | null | no | — |
name | string | null | no | — |
organisationId | string (uuid) | null | no | — |
publicKeyJwk | string | null | no | — |
publicKeyRegisteredAt | string (date-time) | null | no | — |
publicKeyThumbprint | string | null | no | — |
status | DelegatedAgentStatus | no | — |
suspendedAt | string (date-time) | null | no | — |
suspendedForIncidentId | string (uuid) | null | no | — |
suspensionReason | string | null | no | — |
suspensionReference | string | null | no | — |
DelegatedAgentStatus
0 | 1 | 2 with no declared properties.
DeleteDeviceResult
| Property | Type | Required | Description |
|---|---|---|---|
message | string | null | no | — |
sessionsRevoked | integer (int32) | no | — |
success | boolean | no | — |
DesignateSafeguardingOfficerRequest
Request body for designating an officer.
| Property | Type | Required | Description |
|---|---|---|---|
officerReference | string | null | no | Optional opaque, authority-chosen, non-PII reference (a warrant or staff number). |
officerUserId | string (uuid) | no | The officer's user-principal id. |
DetectedAccountResult
| Property | Type | Required | Description |
|---|---|---|---|
accountId | string (uuid) | no | — |
detectedAt | string (date-time) | no | — |
domain | string | null | no | — |
domainProofId | string (uuid) | no | — |
emailMasked | string | null | no | — |
state | string | null | no | — |
subjectId | string (uuid) | no | — |
DeviceDto
| Property | Type | Required | Description |
|---|---|---|---|
createdAt | string (date-time) | no | — |
deviceType | DeviceType | no | — |
fingerprint | string | null | no | — |
friendlyName | string | null | no | — |
id | string (uuid) | no | — |
ipAddress | string | null | no | — |
lastIpAddress | string | null | no | — |
lastUsedAt | string (date-time) | null | no | — |
trustLevel | DeviceTrustLevel | no | — |
trustedAt | string (date-time) | null | no | — |
updatedAt | string (date-time) | null | no | — |
userAgent | string | null | no | — |
userId | string (uuid) | no | — |
DeviceLimitPause
| Property | Type | Required | Description |
|---|---|---|---|
activeDevices | ActiveDeviceSummary[] | null | no | — |
allowance | integer (int64) | no | — |
challengeToken | string | null | no | — |
expiresAt | string (date-time) | no | — |
message | string | null | no | — |
upgradeMessage | string | null | no | — |
DeviceTrustLevel
0 | 1 | 2 | 3 with no declared properties.
DeviceType
0 | 1 | 2 | 3 | 4 | 5 with no declared properties.
DisableMfaCommand
| Property | Type | Required | Description |
|---|---|---|---|
currentPassword | string | null | no | — |
userId | string (uuid) | no | — |
DisableMfaResult
| Property | Type | Required | Description |
|---|---|---|---|
message | string | null | no | — |
success | boolean | no | — |
DiscoverRealmRequest
Request for `POST /discover`. Supply exactly one identifier: `host` for an org-branded sign-in URL, or `email`/`emailHash` for a general user. `host` takes precedence. All fields are optional — a request with none is answered with the region-default realm, the same as any unresolved identifier, so an empty probe is not distinguishable either.
| Property | Type | Required | Description |
|---|---|---|---|
domain | string | null | no | The sign-in address's email DOMAIN, for clients that prefer not to send the address at all. Wins over the domain derived from Essence.Identity.Auth.Api.Controllers.DiscoverRealmRequest.Email. |
email | string | null | no | General user's sign-in address. Only its DOMAIN is used to resolve a realm and only the domain is forwarded to the registry; the address itself is never stored or forwarded, and its hash is used only as the internal audit trail's subject reference (#8633). |
emailHash | string | null | no | Pre-computed SHA-256 hex of the lower-cased address. Retained as the audit subject reference for clients that send neither the address nor the domain; it resolves no realm, because a key the caller chooses and the answer varies with is an account-existence oracle (#8633). |
host | string | null | no | Org-branded sign-in host, e.g. `acme.gb.onessence.digital`. |
DiscoverRealmResponse
Response for `POST /discover` — where to broker the sign-in. Deliberately carries no "resolved" flag: whether the identifier was known is exactly what NFR-09.020 forbids disclosing.
| Property | Type | Required | Description |
|---|---|---|---|
authorizeUrl | string | null | no | The completing instance's OIDC authorize endpoint to redirect to. |
realmToken | string | null | no | Registry-signed, short-TTL realm-redirect descriptor. Opaque to the client. |
region | string | null | no | ISO-3166 alpha-2 region of the completing instance. |
state | string | null | no | Opaque continuation value to carry through the redirect as the OIDC `state`. |
DomainDetectionResult
| Property | Type | Required | Description |
|---|---|---|---|
accounts | DetectedAccountResult[] | null | no | — |
completedAt | string (date-time) | no | — |
domain | string | null | no | — |
domainProofId | string (uuid) | no | — |
runId | string (uuid) | no | — |
DormancyInfo
| Property | Type | Required | Description |
|---|---|---|---|
effectiveThresholdMonths | integer (int32) | null | no | — |
isDormantReactivation | boolean | no | — |
lastActiveLabel | string | null | no | — |
monthsInactive | integer (int32) | no | — |
thresholdSource | string | null | no | — |
EmergencyFreezeRequest
Request body for the emergency freeze. `reason` is an optional non-PII token.
| Property | Type | Required | Description |
|---|---|---|---|
reason | string | null | no | Why the freeze is being placed (e.g. `suspected-account-takeover`). |
EmergencyFreezeResponse
Response for a successful emergency freeze.
| Property | Type | Required | Description |
|---|---|---|---|
frozenAt | string (date-time) | no | UTC instant the freeze is in force from. |
incidentId | string (uuid) | no | The takeover incident the freeze opened or joined (#7393). |
sessionsTerminated | integer (int32) | no | Number of active sessions terminated by the freeze. |
EnableMfaWithTotpResult
| Property | Type | Required | Description |
|---|---|---|---|
backupCodes | string[] | null | no | — |
qrCodeBase64 | string | null | no | — |
qrCodeUri | string | null | no | — |
success | boolean | no | — |
totpSecret | string | null | no | — |
EndAdviserCaseAssignmentRequest
Request body for closing a case.
| Property | Type | Required | Description |
|---|---|---|---|
reason | string | null | no | Why the case is closing. |
EnrolAlternateCredentialRequest
Body of `PUT /api/v1/users/me/protection-status/alternate-credential`. Carries the client-derived hash of the alternate passphrase and nothing else — zero-knowledge: the passphrase itself never reaches the server.
| Property | Type | Required | Description |
|---|---|---|---|
passwordHash | string | null | no | Client-derived hash of the alternate passphrase (same derivation as sign-in). |
EnrolRecoveryPhraseRequest
Request body for `POST /recovery-phrase/enrol`. Essence.Identity.Auth.Api.Controllers.EnrolRecoveryPhraseRequest.RecoveryProof is the client-derived recovery proof (hex, ≥ 64 chars) — never the 24-word phrase or the seed.
| Property | Type | Required | Description |
|---|---|---|---|
recoveryProof | string | null | no | — |
EnrolSupportAgentRequestBody
Request body for enrolling a support agent.
| Property | Type | Required | Description |
|---|---|---|---|
appId | string (uuid) | no | — |
displayName | string | null | no | — |
email | string | null | no | — |
role | string | null | no | — |
EstablishActingAsSessionRequest
Request body for establishing an acting-as session.
| Property | Type | Required | Description |
|---|---|---|---|
grantId | string (uuid) | no | — |
EstablishActingAsSessionResult
| Property | Type | Required | Description |
|---|---|---|---|
actingAsToken | string | null | no | — |
capabilities | string[] | null | no | — |
delegationId | string (uuid) | no | — |
expiresAt | string (date-time) | no | — |
grantId | string (uuid) | no | — |
principalUserId | string (uuid) | no | — |
surface | string | null | no | — |
tokenId | string | null | no | — |
EstablishGuardianshipRequest
Request body for establishing a guardianship (Step 1 seam).
| Property | Type | Required | Description |
|---|---|---|---|
childDisplayName | string | null | no | The guardian-supplied ward display label. |
childId | string (uuid) | null | no | Optional pre-existing minor platform id; when absent a fresh id is minted. |
guardians | GuardianLinkDto[] | null | no | The named guardian links. Must contain exactly one primary. |
ExecutorOfficerAttestationResult
| Property | Type | Required | Description |
|---|---|---|---|
attested | boolean | no | — |
officerUserId | string (uuid) | no | — |
organizationId | string (uuid) | no | — |
verifiedAt | string (date-time) | null | no | — |
ExecutorOfficerRow
| Property | Type | Required | Description |
|---|---|---|---|
attested | boolean | no | — |
officerReference | string | null | no | — |
officerUserId | string (uuid) | no | — |
removalReason | string | null | no | — |
removedAt | string (date-time) | null | no | — |
rosteredAt | string (date-time) | no | — |
status | string | null | no | — |
verificationLevel | string | null | no | — |
verifiedAt | string (date-time) | null | no | — |
ExecutorRosterResult
| Property | Type | Required | Description |
|---|---|---|---|
officers | ExecutorOfficerRow[] | null | no | — |
organizationId | string (uuid) | no | — |
totalCount | integer (int32) | no | — |
verifiedCount | integer (int32) | no | — |
ExpiringVerificationRow
| Property | Type | Required | Description |
|---|---|---|---|
checkType | string | null | no | — |
daysToExpiry | integer (int32) | no | — |
lastReminderSentAt | string (date-time) | null | no | — |
recheckRequestedAt | string (date-time) | null | no | — |
status | string | null | no | — |
subjectReference | string | null | no | — |
validFrom | string (date-time) | no | — |
validUntil | string (date-time) | no | — |
verificationId | string (uuid) | no | — |
ExpiringVerificationsCohortResult
| Property | Type | Required | Description |
|---|---|---|---|
expiredCount | integer (int32) | no | — |
organizationId | string (uuid) | no | — |
recheckRequestedCount | integer (int32) | no | — |
rows | ExpiringVerificationRow[] | null | no | — |
totalCount | integer (int32) | no | — |
windowDays | integer (int32) | no | — |
ExtendProofChallengeRequest
Extension request.
| Property | Type | Required | Description |
|---|---|---|---|
byDays | number (double) | no | How many more days to allow. Bounded by the aggregate. |
FieldAttestationResult
| Property | Type | Required | Description |
|---|---|---|---|
assurance | string | null | no | — |
attestationId | string (uuid) | no | — |
fieldKey | string | null | no | — |
status | string | null | no | — |
FreezeBySignedLinkRequest
Request body for the signed-link emergency freeze — the four fields carried by an FR-66.114 freeze deep link (`?account=&session=&exp=&sig=`).
| Property | Type | Required | Description |
|---|---|---|---|
accountId | string (uuid) | no | Account the link authorises a freeze on. |
expiresAtUnix | integer (int64) | no | Link expiry, seconds since the Unix epoch. |
recoverySessionId | string | null | no | The in-flight recovery attempt the link names. |
signature | string | null | no | Lower-case hex HMAC-SHA256 digest minted by EPIC 66. |
FreezeBySignedLinkResponse
Response for a signed-link freeze. Every field exists so the landing page can state what it actually stopped rather than a generic success — the reader is deciding whether they still need to ring support tonight.
| Property | Type | Required | Description |
|---|---|---|---|
alreadyFrozen | boolean | no | Whether the freeze was already in force before this call. |
frozenAt | string (date-time) | null | no | UTC instant the freeze is in force from. |
recoveryDiscarded | boolean | no | Whether an in-flight recovery attempt was actually discarded. False when the named attempt had already finished, or is owned by a bounded context Auth cannot halt — never rounded up. |
sessionsTerminated | integer (int32) | no | Active sessions terminated by the freeze. |
GrantApprovalDecisionRequest
Request body for an owner's decision, matching the org-portal's `GrantApprovalDecision`. Deliberately carries NO approver identity — that is resolved from the caller's JWT.
| Property | Type | Required | Description |
|---|---|---|---|
decision | string | null | no | — |
reason | string | null | no | — |
GrantDelegateAccessRequest
Wire body for granting delegate access.
| Property | Type | Required | Description |
|---|---|---|---|
authorityBasis | string | null | no | — |
capabilities | string[] | null | no | — |
delegateUserId | string (uuid) | no | — |
delegationId | string (uuid) | no | — |
expiresAt | string (date-time) | null | no | — |
partnerAppId | string (uuid) | null | no | Partner support impersonation only (`authorityBasis=support-impersonation`): the EPIC 25 partner application the acting agent belongs to. Required for that basis so the dual-identity audit can name the partner, not only the person. |
principalUserId | string (uuid) | null | no | Optional explicit principal. Defaults to the caller; any other value is refused (403). |
reasonCode | string | null | no | Partner support impersonation only: the governed reason code from the partner's configured set (an operational token, never free prose). |
surface | string | null | no | — |
ticketReference | string | null | no | Partner support impersonation only: the partner's own ticket reference, exactly as shown to the subject on the consent screen. |
GrantProbateRoleRequest
Wire body for the EPIC 15 → EPIC 9 probate-role grant call.
| Property | Type | Required | Description |
|---|---|---|---|
attorneyUserId | string (uuid) | no | — |
estateId | string (uuid) | null | no | — |
expiresAt | string (date-time) | null | no | — |
grantedByUserId | string (uuid) | null | no | Optional explicit supervising-partner attribution (org-portal direct grants). |
grantorUserId | string (uuid) | null | no | — |
jurisdiction | string | null | no | — |
poaId | string (uuid) | null | no | — |
poaType | string | null | no | — |
scope | ProbateRoleScopeRequest | no | — |
GuardianLinkDto
| Property | Type | Required | Description |
|---|---|---|---|
guardianId | string (uuid) | no | — |
isPrimary | boolean | no | — |
relationship | string | null | no | — |
role | string | null | no | — |
scope | string | null | no | — |
GuardianRosterDto
| Property | Type | Required | Description |
|---|---|---|---|
childDisplayName | string | null | no | — |
childId | string | null | no | — |
guardians | GuardianSeatDto[] | null | no | — |
guardianshipId | string | null | no | — |
status | string | null | no | — |
GuardianSeatDto
| Property | Type | Required | Description |
|---|---|---|---|
activatedAtIso | string | null | no | — |
guardianId | string | null | no | — |
isActive | boolean | no | — |
isPrimary | boolean | no | — |
relationship | string | null | no | — |
role | string | null | no | — |
scope | string | null | no | — |
GuardianshipCorroborationResult
| Property | Type | Required | Description |
|---|---|---|---|
corroborated | boolean | no | — |
guardianId | string (uuid) | no | — |
guardianshipId | string (uuid) | null | no | — |
minorSubjectId | string (uuid) | no | — |
GuardianshipResultDto
| Property | Type | Required | Description |
|---|---|---|---|
childId | string | null | no | — |
guardianshipId | string | null | no | — |
HandoverConfirmationDto
| Property | Type | Required | Description |
|---|---|---|---|
guardianAccessEnded | boolean | no | — |
revocationDateIso | string | null | no | — |
revokedGuardianIds | (string (uuid))[] | null | no | — |
status | string | null | no | — |
subjectId | string (uuid) | no | — |
whoHasAccess | (string (uuid))[] | null | no | — |
IdentityAttestation
| Property | Type | Required | Description |
|---|---|---|---|
attestedAt | string (date-time) | no | — |
auditAnchorReference | string | null | no | — |
evidenceKinds | string[] | null | no | — |
level | string | null | no | — |
verifier | string | null | no | — |
IdentityAttestedReprovisionRequest
| Property | Type | Required | Description |
|---|---|---|---|
newPasswordHash | string | null | no | — |
proofingSessionId | string (uuid) | no | — |
requestVaultReprovision | boolean | no | — |
subjectUserId | string (uuid) | no | — |
IdentityAttestedReprovisionResult
| Property | Type | Required | Description |
|---|---|---|---|
attestation | IdentityAttestation | no | — |
recoveryMaterialSurveyed | string | null | no | — |
reprovisionId | string (uuid) | no | — |
reprovisionedAt | string (date-time) | no | — |
subjectUserId | string (uuid) | no | — |
vaultReprovisionRequested | boolean | no | — |
IdentityChangeRecordDto
| Property | Type | Required | Description |
|---|---|---|---|
changedAtIso | string | null | no | — |
from | string | null | no | — |
guardianshipId | string (uuid) | null | no | — |
identityChangeRef | string | null | no | — |
subjectId | string (uuid) | no | — |
to | string | null | no | — |
IndividualRecoveryCancelBody
| Property | Type | Required | Description |
|---|---|---|---|
cancelToken | string | null | no | The token from the text message's link. |
IndividualRecoveryCancelResponse
| Property | Type | Required | Description |
|---|---|---|---|
cancelled | boolean | no | — |
IndividualRecoveryCompleteBody
| Property | Type | Required | Description |
|---|---|---|---|
completionToken | string | null | no | The token the proof step returned. |
newPasswordHash | string | null | no | The CLIENT-DERIVED verifier of the new password; never the password itself. |
IndividualRecoveryCompleteResponse
| Property | Type | Required | Description |
|---|---|---|---|
completed | boolean | no | True when the new credential is set. |
secondFactorReenrolmentRequired | boolean | no | Always true: every old factor was removed. |
IndividualRecoveryProofBody
The two codes: one from the email of record, one from the verified phone.
| Property | Type | Required | Description |
|---|---|---|---|
emailCode | string | null | no | — |
smsCode | string | null | no | — |
IndividualRecoveryProofResponse
| Property | Type | Required | Description |
|---|---|---|---|
completeBy | string (date-time) | no | The latest it can be completed (UTC); after it, start again. |
completionToken | string | null | no | Shown once. Keep it: it is the only way to finish this recovery. |
holdEndsAt | string (date-time) | no | The earliest the recovery can be completed (UTC). |
InitiateOAuthLinkRequest
Request model for starting a link flow (`{provider}/link/authorize`). Carries no user id: the account to link is the signed-in caller, read from the bearer token.
| Property | Type | Required | Description |
|---|---|---|---|
redirectUri | string | null | no | Redirect URI where the OAuth provider will send the authorization code. Must match exactly with the URI registered with the provider. |
scopes | string[] | null | no | Optional scopes to request. If not provided, default scopes will be used. |
InitiateOAuthRequest
Request model for initiating OAuth flow.
| Property | Type | Required | Description |
|---|---|---|---|
deviceFingerprint | string | null | no | Optional device fingerprint for device tracking. |
homeRegion | string | null | no | Optional sovereign home region chosen on the sign-up surface (ISO 3166-1 alpha-2, e.g. "GB"/"DE"/"AE"; FR-44.040, D-123). Stored in the OAuth state and applied when the callback creates a NEW account, so the account and its default vault are provisioned in the chosen region. "GLOBAL" and blank are not valid regions and fall back to the sovereign default (counted as an onboarding fault). |
redirectUri | string | null | no | Redirect URI where the OAuth provider will send the authorization code. Must match exactly with the URI registered with the provider. |
scopes | string[] | null | no | Optional scopes to request. If not provided, default scopes will be used. |
InitiateOAuthResult
| Property | Type | Required | Description |
|---|---|---|---|
authorizationUrl | string | null | no | — |
codeVerifier | string | null | no | — |
expiresAt | string (date-time) | no | — |
state | string | null | no | — |
InitiateProbateStepUpRequest
Request body for initiating a probate step-up. `authorityBasis` and `factor` carry the contract's kebab-case wire values (`court-grant` | `probate-role`; `email` | `sms` | `webauthn` | `phone-call` | `postal-code`) — see Essence.Identity.Auth.Api.Controllers.SendProbateStepUpChallengeRequest for why they are strings.
| Property | Type | Required | Description |
|---|---|---|---|
authorityBasis | string | null | no | — |
estateId | string (uuid) | no | — |
factor | string | null | no | — |
factorProof | string | null | no | — |
grantDocumentId | string | null | no | — |
grantReference | string | null | no | — |
InitiateProofingRequest
Body for initiating a proofing session (capability (c)).
| Property | Type | Required | Description |
|---|---|---|---|
provider | string | null | no | The proofing provider to route to (defaults to `self-serve`). |
relyingServiceId | string | null | no | The relying service / gated action this run is for (e.g. `loan-drawdown`) — the key the governing org's assurance-threshold policy is resolved by (debt-2026-08-13-211). |
requiredLevel | string | null | no | The level the requesting action says it needs (`loa1`|`loa2`|`loa3`). Advisory only: the org policy resolved server-side may raise it, and a caller can never lower what its organisation demands. |
InitiateSafeRecoveryRequestBody
Request body for initiating safe recovery.
| Property | Type | Required | Description |
|---|---|---|---|
reason | string | null | no | Optional short, non-PII reason. |
InitiateSafeRecoveryResult
| Property | Type | Required | Description |
|---|---|---|---|
claimId | string (uuid) | no | — |
initiatedAtIso | string | null | no | — |
status | string | null | no | — |
InitiateStepUpRequest
Request body for initiating a generic step-up. `action` and `factor` carry the contract's kebab-case wire values (`recovery-initiate` | `password-change` | `verification-renewal`; `totp` | `sms` | `email` | `webauthn`).
| Property | Type | Required | Description |
|---|---|---|---|
action | string | null | no | — |
factor | string | null | no | — |
factorProof | string | null | no | — |
passwordHash | string | null | no | The client-derived password hash, REQUIRED for actions that need password re-verification in addition to a second factor — today `account-closure` (FR-15.008.7, debt-2026-08-19-008). Zero-knowledge: the same client-side hash the login and change-password contracts carry. The plaintext password never reaches the server; the comparison is constant-time in the domain. Omit for every action a second factor alone elevates. |
reactivationCorrelationId | string | null | no | Optional correlation id from the flow requesting the elevation (e.g. the dormant-account reactivation). Echoed onto the emitted `SessionElevatedIntegrationEvent` for cross-service audit correlation (debt-2026-07-08-107). Ignored for non-correlated actions. |
resourceBinding | string | null | no | Optional opaque reference to the single resource the elevation is for — e.g. the contact card id being re-attested with `action=connection-trust-action` (debt-2026-08-13-009). Stamped onto the token's `rsc` claim so a consumer can refuse an elevation taken for a different resource. Omit for account-wide elevations. |
InitiateStepUpResponse
Wire form of Essence.Identity.Auth.Application.Commands.StepUp.InitiateStepUpResult (#10652).
| Property | Type | Required | Description |
|---|---|---|---|
assertion | StepUpAssertionResponse | no | — |
expiresAt | string (date-time) | no | — |
maxExpiresAt | string (date-time) | no | — |
sessionId | string | null | no | — |
stepUpToken | string | null | no | — |
warnAt | string (date-time) | no | — |
InvitationDetailDto
| Property | Type | Required | Description |
|---|---|---|---|
department | string | null | no | — |
email | string | null | no | — |
emailMasked | string | null | no | — |
expiresAt | string (date-time) | no | — |
homeRegion | string | null | no | — |
invitationId | string (uuid) | no | — |
invitedByDisplayName | string | null | no | — |
onboarding | InvitationOnboardingDto | no | — |
organizationId | string (uuid) | no | — |
organizationName | string | null | no | — |
roles | InvitationRoleDto[] | null | no | — |
sponsoredPremium | InvitationSponsoredPremiumDto | no | — |
status | string | null | no | — |
vaultScope | InvitationVaultScopeDto | no | — |
InvitationOnboardingDto
| Property | Type | Required | Description |
|---|---|---|---|
requiresMfa | boolean | no | — |
requiresPhoneVerification | boolean | no | — |
requiresRecovery | boolean | no | — |
InvitationRoleDto
| Property | Type | Required | Description |
|---|---|---|---|
description | string | null | no | — |
name | string | null | no | — |
roleId | string (uuid) | no | — |
InvitationSponsoredPremiumDto
| Property | Type | Required | Description |
|---|---|---|---|
entitlementLabel | string | null | no | — |
planLabel | string | null | no | — |
sponsorName | string | null | no | — |
InvitationVaultScopeDto
| Property | Type | Required | Description |
|---|---|---|---|
access | string | null | no | — |
description | string | null | no | — |
vaultLabel | string | null | no | — |
InviteOrganizationMemberRequest
Request body for inviting an organisation member. Carries the invitee and nothing else: the organisation is in the route, the inviter is in the token, and no role may be pre-assigned.
| Property | Type | Required | Description |
|---|---|---|---|
inviteeEmail | string | null | no | The person being invited. |
InviteOrganizationMemberResult
| Property | Type | Required | Description |
|---|---|---|---|
expiresAt | string (date-time) | no | — |
invitationId | string (uuid) | no | — |
IssueMajorityTransitionRekeyTokenResult
| Property | Type | Required | Description |
|---|---|---|---|
claimId | string (uuid) | no | — |
expiresAtIso | string | null | no | — |
purpose | string | null | no | — |
token | string | null | no | — |
IssueOutOfBandProofChallengeResult
| Property | Type | Required | Description |
|---|---|---|---|
challengeId | string (uuid) | no | — |
channel | OutOfBandProofChannel | no | — |
delivered | boolean | no | — |
deliveryHint | string | null | no | — |
expiresAt | string (date-time) | no | — |
expiryConsequence | string | null | no | — |
extensionsRemaining | integer (int32) | no | — |
reused | boolean | no | — |
IssueProofChallengeRequest
Issuance request. Carries NO destination — see the controller remarks.
| Property | Type | Required | Description |
|---|---|---|---|
caseRef | string | null | no | Opaque correlation handle for the requesting case. |
channel | OutOfBandProofChannel | no | — |
expiryConsequence | string | null | no | REQUIRED. What the holder is told happens if the window lapses. |
purpose | string | null | no | Bounded slug describing why, e.g. `merge-adjudication`. |
subjectAccountId | string (uuid) | no | The account whose control is being tested. |
windowDays | number (double) | null | no | Optional override of the default (7-day) window, in days. |
IssueScopedAdminGrantRequest
Request body for issuing a scoped-admin grant, matching the org-portal's `IssueScopedAdminGrantRequest`. Deliberately carries NO issuer identity — that is resolved from the caller's JWT.
| Property | Type | Required | Description |
|---|---|---|---|
approvalPolicy | string | null | no | Kebab-case: `none` | `single-owner` | `dual-owner`. |
delegateName | string | null | no | Display name shown on the co-sign card. |
delegateRef | string | null | no | Pseudonymous reference of the staff member receiving the authority. |
expiresAt | string (date-time) | null | no | Optional UTC expiry; null issues an open-ended grant. |
justification | string | null | no | The owner's business rationale (recorded to audit). |
roleName | string | null | no | The scoped-role display name being granted. |
scopeActions | string[] | null | no | Action verbs the grant confers. |
scopeModules | string[] | null | no | Business modules the grant reaches. |
IssueSmartLaunchContextRequest
Wire body for minting a launch context.
| Property | Type | Required | Description |
|---|---|---|---|
clientId | string | null | no | The SMART app being launched. |
encounterRef | string | null | no | Opaque vendor encounter reference, when in context. |
iss | string | null | no | The launching EHR's FHIR base URL. |
lifetimeSeconds | integer (int32) | null | no | Requested lifetime in seconds (30–900). |
offeredScopes | string[] | null | no | Explicit scope array; takes precedence over Essence.Identity.Auth.Api.Controllers.IssueSmartLaunchContextRequest.Scope. |
patientRef | string | null | no | Opaque vendor patient reference. |
scope | string | null | no | Space-delimited scopes the EHR authorises for this launch. |
IssueSmartLaunchContextResult
| Property | Type | Required | Description |
|---|---|---|---|
expiresAt | string (date-time) | no | — |
launchContextId | string (uuid) | no | — |
launchToken | string | null | no | — |
JsonWebKey
JSON Web Key structure (JWK).
| Property | Type | Required | Description |
|---|---|---|---|
alg | string | null | no | Algorithm (RS256). |
e | string | null | no | RSA public exponent (base64url encoded). |
kid | string | null | no | Key ID. |
kty | string | null | no | Key type (RSA). |
n | string | null | no | RSA modulus (base64url encoded). |
use | string | null | no | Public key use (sig = signature). |
JwksDocument
JSON Web Key Set document structure (RFC 7517 §5).
| Property | Type | Required | Description |
|---|---|---|---|
keys | JsonWebKey[] | null | no | — |
LoginCommand
| Property | Type | Required | Description |
|---|---|---|---|
deviceFingerprint | string | null | no | — |
deviceType | string | null | no | — |
email | string | null | no | — |
ipAddress | string | null | no | — |
passwordHash | string | null | no | — |
preferEmailStepUp | boolean | no | — |
rememberDevice | boolean | no | — |
userAgent | string | null | no | — |
LoginMethodDto
A single presented login method, in presentation order.
| Property | Type | Required | Description |
|---|---|---|---|
available | boolean | no | Whether a sign-in can be completed through this method right now. A method used to have one state — whether it appeared at all — so a region whose national IdP is <b>registered but not switched on here</b> answered byte-identically to a region that has <b>no national IdP</b>, and a US resident was shown a screen that said, in effect, that no federal way into Essence exists (#12291). Those are opposite facts. A named entry with `available: false` is the first one; no entry at all is still the second. An `available: false` method must NOT be rendered as a clickable control — that is the whole of #6945, which this does not relax: a national-IdP button carrying a placeholder `client_id` hands the person to the real IdP, which refuses on its own unbranded page with no route back. It is rendered named, disabled and explained. `true` for every method the policy has always presented, so a client that does not read this field sees exactly the list it saw before. |
displayName | string | null | no | — |
id | string | null | no | — |
kind | string | null | no | — |
provider | string | null | no | — |
unavailableReason | string | null | no | Why the method is unavailable — `"not-configured"` (the provider is registered for this region but this instance holds no usable credential for it, the presentation twin of the authorize route's 501 `federated-provider-not-configured`). Null when Essence.Identity.Auth.Api.Controllers.LoginMethodDto.Available is true. |
LoginMethodsResponse
Response for `GET /login-methods` — the ordered presentation list.
| Property | Type | Required | Description |
|---|---|---|---|
methods | LoginMethodDto[] | null | no | — |
nationalIdp | string | null | no | What can be said about the region's national sign-in (EPIC 9 FR-09.060): `available` | `not-configured` | `none-in-region` | `region-not-stated`. `none-in-region` means the platform has no national-IdP connector for the region, which the sign-in screen says in words — before this field that region answered with nothing, the same blank a failed load would leave. |
region | string | null | no | — |
socialProviders | string[] | null | no | The consumer social providers this instance offers at SIGN-UP (FR-44.005) — provider slugs (`Google` / `Apple` / `Microsoft`) the provider picker may present. <b>Always stated, never null.</b> An EMPTY array means this instance offers no consumer social provider — either because the operator disabled them or because none holds a usable credential — and the picker renders that as a real state. It used to carry the operator's raw allow-list, whose `null` ("no restriction configured") the picker read as "offer every provider", so a silent instance advertised three providers it could not serve (#6527). The same resolved set drives the !:LoginMethodKind.Social entries in Essence.Identity.Auth.Api.Controllers.LoginMethodsResponse.Methods, which is the SIGN-IN presentation of the same providers — so the promise onboarding makes ("your provider can sign you back in") cannot come apart from what the sign-in surface offers. |
LoginResult
| Property | Type | Required | Description |
|---|---|---|---|
accessToken | string | null | no | — |
accessTokenExpiresAt | string (date-time) | no | — |
approvalRequired | boolean | no | — |
approvalToken | string | null | no | — |
deviceLimit | DeviceLimitPause | no | — |
deviceLimitReached | boolean | no | — |
dormancy | DormancyInfo | no | — |
email | string | null | no | — |
emailVerified | boolean | no | — |
firstName | string | null | no | — |
lastName | string | null | no | — |
mfaChallengeToken | string | null | no | — |
mfaCodeDelivered | boolean | null | no | — |
mfaCodeDeliveryStatus | string | null | no | — |
mfaCodeRetryAfterSeconds | integer (int32) | null | no | — |
mfaMethod | string | null | no | — |
mfaRequired | boolean | no | — |
refreshToken | string | null | no | — |
refreshTokenExpiresAt | string (date-time) | no | — |
stepUpMethod | string | null | no | — |
stepUpReason | string | null | no | — |
userId | string (uuid) | no | — |
LogoutCommand
| Property | Type | Required | Description |
|---|---|---|---|
refreshToken | string | null | no | — |
revokeAllSessions | boolean | no | — |
LogoutResult
| Property | Type | Required | Description |
|---|---|---|---|
sessionsRevoked | integer (int32) | no | — |
success | boolean | no | — |
MediumEnrolmentOptionsDto
| Property | Type | Required | Description |
|---|---|---|---|
enrolledRoutes | integer (int32) | no | — |
minimumRoutes | integer (int32) | no | — |
requiredLevel | string | null | no | — |
routes | MediumEnrolmentRouteDto[] | null | no | — |
MediumEnrolmentRouteDto
| Property | Type | Required | Description |
|---|---|---|---|
enrolled | boolean | no | — |
level | string | null | no | — |
method | string | null | no | — |
notOfferedReason | string | null | no | — |
offered | boolean | no | — |
prerequisite | string | null | no | — |
setUpEndpoint | string | null | no | — |
MemberInvitationTokenRequest
Request body for the two authenticated invitation actions. Carries the token and nothing else: the account, the device and the session all come from the caller's JWT, so there is no field here by which a caller could name somebody other than themselves.
| Property | Type | Required | Description |
|---|---|---|---|
token | string | null | no | The opaque token from the invitation link. |
MergePolicyDecisionInput
| Property | Type | Required | Description |
|---|---|---|---|
acknowledgedDisclosure | boolean | no | — |
decidedAt | string (date-time) | null | no | — |
orgName | string | null | no | — |
overridden | boolean | no | — |
reason | string | null | no | — |
templateInForce | string | null | no | — |
MergeStageProgressDto
| Property | Type | Required | Description |
|---|---|---|---|
stage | string | null | no | — |
state | string | null | no | — |
MergeStepUpDto
A step-up factor + proof value supplied with the destructive merge confirm.
| Property | Type | Required | Description |
|---|---|---|---|
factor | string | null | no | The step-up factor name (Totp | Sms | Email | WebAuthn), case-insensitive. |
value | string | null | no | The proof value: an OTP code, or a WebAuthn assertion JSON payload. |
MfaMethod
0 | 1 | 2 | 3 | 4 | 5 with no declared properties.
MfaStatusDto
| Property | Type | Required | Description |
|---|---|---|---|
backupCodesIssued | integer (int32) | no | — |
backupCodesRemaining | integer (int32) | no | — |
emailEnabled | boolean | no | — |
smsEnabled | boolean | no | — |
totpEnabled | boolean | no | — |
NameBearingCredentialInput
| Property | Type | Required | Description |
|---|---|---|---|
credentialClass | string | null | no | — |
credentialId | string (uuid) | no | — |
label | string | null | no | — |
NameChangeHistoryExport
| Property | Type | Required | Description |
|---|---|---|---|
accountId | string (uuid) | no | — |
auditAnchorRef | string | null | no | — |
auditRecordId | string (uuid) | no | — |
committedAt | string (date-time) | no | — |
exportedAt | string (date-time) | no | — |
format | string | null | no | — |
newNameHash | string | null | no | — |
notifiedCount | integer (int32) | no | — |
previousNameDisposition | string | null | no | — |
previousNameHash | string | null | no | — |
reattestedAt | string (date-time) | no | — |
recordType | string | null | no | — |
withheldCount | integer (int32) | no | — |
NewDeviceFreezeLinkRequest
The two values the alert's link carries.
| Property | Type | Required | Description |
|---|---|---|---|
alertId | string (uuid) | no | The alert (new-device event) id. |
token | string | null | no | The link's single-use token. |
NewDeviceFreezeLinkResponse
A live link was used: the account is frozen.
| Property | Type | Required | Description |
|---|---|---|---|
frozen | boolean | no | — |
NonCustodyAttestationDto
| Property | Type | Required | Description |
|---|---|---|---|
actionCount | integer (int32) | no | — |
asOf | string (date-time) | no | — |
assistantUserId | string (uuid) | no | — |
assistedUserId | string (uuid) | no | — |
expiresAt | string (date-time) | null | no | — |
grantId | string (uuid) | no | — |
keyMaterialAccessed | boolean | no | — |
nonCustodyAttested | boolean | no | — |
sessionId | string (uuid) | no | — |
statement | string | null | no | — |
status | string | null | no | — |
OAuthCallbackRequest
Request model for OAuth callback. Carries no link target: whether a callback links, and to whom, is decided by the one-time state (see `{provider}/link/authorize`), never the body.
| Property | Type | Required | Description |
|---|---|---|---|
authorizationCode | string | null | no | Authorization code received from the OAuth provider. |
codeVerifier | string | null | no | PKCE code verifier generated during authorization initiation. |
deviceFingerprint | string | null | no | Optional device fingerprint for device creation/tracking. |
homeRegion | string | null | no | Fallback sovereign home region for a NEW account (ISO 3166-1 alpha-2; FR-44.040, D-123). The region carried in the OAuth state (chosen before redirect) wins; this is used only when the state carries none. Ignored when the identity resolves to an existing or linked account. |
redirectUri | string | null | no | Redirect URI used in the authorization request. Must match exactly for security. |
state | string | null | no | State parameter for CSRF protection. |
OAuthCallbackResult
| Property | Type | Required | Description |
|---|---|---|---|
accessToken | string | null | no | — |
accessTokenExpiresAt | string (date-time) | no | — |
accountLinked | boolean | no | — |
deviceLimit | DeviceLimitPause | no | — |
deviceLimitReached | boolean | no | — |
email | string | null | no | — |
emailVerified | boolean | no | — |
grantedScopes | string[] | null | no | — |
homeRegion | string | null | no | — |
isNewUser | boolean | no | — |
isRelayEmail | boolean | no | — |
mfaChallengeToken | string | null | no | — |
mfaCodeDelivered | boolean | null | no | — |
mfaCodeDeliveryStatus | string | null | no | — |
mfaCodeRetryAfterSeconds | integer (int32) | null | no | — |
mfaMethod | string | null | no | — |
mfaRequired | boolean | no | — |
name | string | null | no | — |
provider | string | null | no | — |
refreshToken | string | null | no | — |
refreshTokenExpiresAt | string (date-time) | no | — |
userId | string (uuid) | no | — |
OAuthLinkResult
Response model for OAuth provider linking.
| Property | Type | Required | Description |
|---|---|---|---|
message | string | null | no | Success or error message. |
provider | string | null | no | Identity provider that was linked. |
success | boolean | no | Whether the linking was successful. |
OpenBiometricReenrolmentRequest
Body for opening a re-enrolment session (all optional — the subject is from the token).
| Property | Type | Required | Description |
|---|---|---|---|
lockoutState | string | null | no | — |
memberReference | string | null | no | — |
mismatchReason | string | null | no | — |
OpenIdConfiguration
OpenID Connect discovery document (OIDC Discovery 1.0 §3 / RFC 8414 §2).
| Property | Type | Required | Description |
|---|---|---|---|
authorization_endpoint | string | null | no | — |
claims_supported | string[] | null | no | — |
id_token_signing_alg_values_supported | string[] | null | no | — |
issuer | string | null | no | — |
jwks_uri | string | null | no | — |
response_types_supported | string[] | null | no | — |
scopes_supported | string[] | null | no | — |
subject_types_supported | string[] | null | no | — |
token_endpoint | string | null | no | — |
token_endpoint_auth_methods_supported | string[] | null | no | — |
userinfo_endpoint | string | null | no | — |
OperatingJurisdictionEndedResponse
A declaration that was ended early.
| Property | Type | Required | Description |
|---|---|---|---|
endedAt | string (date-time) | no | When it was ended (UTC). |
jurisdiction | string | null | no | The jurisdiction that had been in force. |
OperatingJurisdictionResponse
The declaration as recorded on the session.
| Property | Type | Required | Description |
|---|---|---|---|
corroborated | boolean | no | Whether the request located to the same jurisdiction. |
declaredAt | string (date-time) | no | When it was recorded (UTC). |
expiresAt | string (date-time) | no | When the session's tokens stop carrying it (UTC). Declare again to continue. |
jurisdiction | string | null | no | The normalised code. |
OperationalRoleCatalogueEntryDto
One grantable role as shown on the administration screen.
| Property | Type | Required | Description |
|---|---|---|---|
capability | string | null | no | The operational capability it belongs to. |
description | string | null | no | What holding it lets the person do. |
displayName | string | null | no | Human label. |
issuedThroughOrgPortal | boolean | no | The role is granted in the organisation portal's Members screen (Module roles), and a grant here is refused with `issued-through-org-portal`. Carried on the catalogue so the administration screen can send the administrator there instead of offering a grant that is certain to be refused (#6191). |
role | string | null | no | The canonical kebab-case claim value. |
OrganisationDelegateAccessPairDto
| Property | Type | Required | Description |
|---|---|---|---|
capabilities | string[] | null | no | — |
delegateLabel | string | null | no | — |
delegateUserId | string (uuid) | no | — |
delegationId | string (uuid) | no | — |
expiresAt | string (date-time) | null | no | — |
grantId | string (uuid) | no | — |
grantedAt | string (date-time) | no | — |
lastActivityAt | string (date-time) | null | no | — |
principalLabel | string | null | no | — |
principalUserId | string (uuid) | no | — |
revokedAt | string (date-time) | null | no | — |
status | DelegateAccessStatus | no | — |
surface | string | null | no | — |
OrganisationDelegateAccessPairDtoCursorResult
| Property | Type | Required | Description |
|---|---|---|---|
hasMore | boolean | no | — |
items | OrganisationDelegateAccessPairDto[] | null | no | — |
nextCursor | string | null | no | — |
pageSize | integer (int32) | no | — |
previousCursor | string | null | no | — |
OrganisationNotificationAudienceDto
| Property | Type | Required | Description |
|---|---|---|---|
organisationRegion | string | null | no | — |
organizationId | string (uuid) | no | — |
recipientIds | (string (uuid))[] | null | no | — |
truncated | boolean | no | — |
OrgIdpRecordDto
Wire shape matching `orgSsoResolution.ts::OrgIdpRecord` (camel-cased by the serializer).
| Property | Type | Required | Description |
|---|---|---|---|
displayName | string | null | no | — |
domain | string | null | no | — |
enterpriseEntitlement | boolean | no | — |
organizationId | string | null | no | — |
protocol | string | null | no | — |
provider | string | null | no | — |
ssoOnly | boolean | no | — |
OrgIdpResolveResponse
Response for `GET /org-idp/resolve`. `Org` is null when not federated.
| Property | Type | Required | Description |
|---|---|---|---|
org | OrgIdpRecordDto | no | — |
OrgMembershipStandingDto
| Property | Type | Required | Description |
|---|---|---|---|
activeMember | boolean | no | — |
administers | boolean | no | — |
organizationId | string (uuid) | no | — |
userId | string (uuid) | no | — |
OrgOperationalRoleHolder
| Property | Type | Required | Description |
|---|---|---|---|
roles | string[] | null | no | — |
userId | string (uuid) | no | — |
OrgOperationalRoleHoldersResult
| Property | Type | Required | Description |
|---|---|---|---|
holders | OrgOperationalRoleHolder[] | null | no | — |
membersScanned | integer (int32) | no | — |
truncated | boolean | no | — |
OrgSsoCoverageDto
| Property | Type | Required | Description |
|---|---|---|---|
coveredDomainCount | integer (int32) | no | — |
memberCount | integer (int32) | null | no | — |
organizationId | string (uuid) | no | — |
resolved | boolean | no | — |
OutcomeRequest
Body for resolving a session terminally.
| Property | Type | Required | Description |
|---|---|---|---|
outcome | string | null | no | — |
OutOfBandProofChallengeStatus
0 | 1 | 2 | 3 | 4 with no declared properties.
OutOfBandProofChallengeView
| Property | Type | Required | Description |
|---|---|---|---|
answeredAt | string (date-time) | null | no | — |
canExtend | boolean | no | — |
caseRef | string | null | no | — |
challengeId | string (uuid) | no | — |
channel | OutOfBandProofChannel | no | — |
expiresAt | string (date-time) | no | — |
expiryConsequence | string | null | no | — |
extensionsGranted | integer (int32) | no | — |
extensionsRemaining | integer (int32) | no | — |
issuedAt | string (date-time) | no | — |
outcome | OutOfBandProofOutcome | no | — |
purpose | string | null | no | — |
resolvedAt | string (date-time) | null | no | — |
status | OutOfBandProofChallengeStatus | no | — |
subjectAccountId | string (uuid) | no | — |
OutOfBandProofChannel
0 | 1 with no declared properties.
OutOfBandProofOutcome
0 | 1 | 2 | 3 | 4 with no declared properties.
PartnerSupportSessionDto
| Property | Type | Required | Description |
|---|---|---|---|
agentDisplayName | string | null | no | — |
agentId | string (uuid) | no | — |
applicationId | string (uuid) | no | — |
consentId | string (uuid) | no | — |
endedAt | string (date-time) | null | no | — |
expiresAt | string (date-time) | null | no | — |
reasonCode | string | null | no | — |
scopes | string[] | null | no | — |
sessionId | string (uuid) | no | — |
startedAt | string (date-time) | no | — |
status | string | null | no | — |
subjectUserReference | string | null | no | — |
terminationReason | string | null | no | — |
ticketReference | string | null | no | — |
PasswordBreachRangeEntryDto
One suffix of the range.
| Property | Type | Required | Description |
|---|---|---|---|
count | integer (int32) | no | How often it occurs in the corpus; 0 marks padding. |
suffix | string | null | no | The remaining 35 upper-case hex characters of a SHA-1 in the corpus. |
PasswordBreachRangeRequest
The request body: the prefix, and nothing else.
| Property | Type | Required | Description |
|---|---|---|---|
prefix | string | null | no | The first 5 upper-case hex characters of SHA-1(password). |
PasswordBreachRangeResponse
The range for one prefix, padding included (wire names fixed regardless of host JSON options).
| Property | Type | Required | Description |
|---|---|---|---|
suffixes | PasswordBreachRangeEntryDto[] | null | no | Every suffix sharing the prefix. |
PasswordlessLoginChallengeRequest
| Property | Type | Required | Description |
|---|---|---|---|
userVerification | string | null | no | Optional override for user verification. Defaults to `required` on the command side — overriding down to `preferred` is tolerated but not encouraged. |
PasswordlessLoginChallengeResult
| Property | Type | Required | Description |
|---|---|---|---|
challenge | string | null | no | — |
rpId | string | null | no | — |
sessionId | string | null | no | — |
timeout | integer (int32) | no | — |
userVerification | string | null | no | — |
PasswordlessLoginRequest
| Property | Type | Required | Description |
|---|---|---|---|
authenticatorData | string | null | no | — |
clientDataJson | string | null | no | — |
credentialId | string | null | no | — |
sessionId | string | null | no | — |
signature | string | null | no | — |
userHandle | string | null | no | Base64url-encoded userHandle returned by the authenticator. |
PasswordlessLoginResult
| Property | Type | Required | Description |
|---|---|---|---|
accessToken | string | null | no | — |
accessTokenExpiresAt | string (date-time) | no | — |
deviceLimit | DeviceLimitPause | no | — |
deviceLimitReached | boolean | no | — |
errorMessage | string | null | no | — |
refreshToken | string | null | no | — |
refreshTokenExpiresAt | string (date-time) | no | — |
success | boolean | no | — |
userId | string (uuid) | no | — |
PendingCustodialOrderItem
| Property | Type | Required | Description |
|---|---|---|---|
documentName | string | null | no | — |
effectiveDateIso | string | null | no | — |
evidenceCodes | string[] | null | no | — |
hasDocument | boolean | no | — |
instrumentCode | string | null | no | — |
instrumentLabel | string | null | no | — |
issuingAuthority | string | null | no | — |
jurisdictionCode | string | null | no | — |
orderId | string | null | no | — |
orderReference | string | null | no | — |
requiredAuthoriser | string | null | no | — |
submittedAtIso | string | null | no | — |
PendingCustodialOrderItemCursorResult
| Property | Type | Required | Description |
|---|---|---|---|
hasMore | boolean | no | — |
items | PendingCustodialOrderItem[] | null | no | — |
nextCursor | string | null | no | — |
pageSize | integer (int32) | no | — |
previousCursor | string | null | no | — |
PendingDeviceApprovalDto
| Property | Type | Required | Description |
|---|---|---|---|
comparisonCode | string | null | no | — |
expiresAt | string (date-time) | no | — |
id | string (uuid) | no | — |
newDeviceId | string (uuid) | no | — |
requestedAt | string (date-time) | no | — |
requesterIp | string | null | no | — |
requesterUserAgent | string | null | no | — |
PendingSupportAccessRequestDto
| Property | Type | Required | Description |
|---|---|---|---|
agentDisplayName | string | null | no | — |
agentPrincipalId | string (uuid) | no | — |
consentId | string (uuid) | no | — |
expiresAt | string (date-time) | no | — |
partnerAppId | string (uuid) | no | — |
partnerApproved | boolean | no | — |
partnerName | string | null | no | — |
partnerNameStatus | string | null | no | — |
publisherName | string | null | no | — |
publisherVerified | boolean | null | no | — |
reasonCode | string | null | no | — |
requestId | string (uuid) | no | — |
requestedAt | string (date-time) | no | — |
requestedDurationMinutes | integer (int32) | no | — |
requestedScopes | string[] | null | no | — |
ticketReference | string | null | no | — |
PhoneVerificationConfirmedResponse
The number is verified.
| Property | Type | Required | Description |
|---|---|---|---|
verified | boolean | no | — |
PhoneVerificationSentResponse
The masked number the code went to, and when it expires.
| Property | Type | Required | Description |
|---|---|---|---|
expiresAt | string (date-time) | no | — |
maskedNumber | string | null | no | — |
PollDeviceApprovalResult
| Property | Type | Required | Description |
|---|---|---|---|
accessToken | string | null | no | — |
accessTokenExpiresAt | string (date-time) | null | no | — |
comparisonCode | string | null | no | — |
refreshToken | string | null | no | — |
refreshTokenExpiresAt | string (date-time) | null | no | — |
status | string | null | no | — |
PreAssignedRoleInput
| Property | Type | Required | Description |
|---|---|---|---|
description | string | null | no | — |
name | string | null | no | — |
roleId | string (uuid) | no | — |
PreferredLocaleResult
| Property | Type | Required | Description |
|---|---|---|---|
changed | boolean | no | — |
preferredLocale | string | null | no | — |
reserveAuditRef | string | null | no | — |
supportedLocales | string[] | null | no | — |
PrimaryContactCascadeEntry
| Property | Type | Required | Description |
|---|---|---|---|
affectedRefCount | integer (int32) | no | — |
consumer | string | null | no | — |
epic | integer (int32) | no | — |
status | string | null | no | — |
PrimaryContactCascadeView
| Property | Type | Required | Description |
|---|---|---|---|
changeId | string (uuid) | no | — |
committedAt | string (date-time) | null | no | — |
consumers | PrimaryContactCascadeEntry[] | null | no | — |
status | string | null | no | — |
PrimaryContactChangeView
| Property | Type | Required | Description |
|---|---|---|---|
accountId | string (uuid) | no | — |
cancelledAt | string (date-time) | null | no | — |
changeId | string (uuid) | no | — |
channel | string | null | no | — |
committedAt | string (date-time) | null | no | — |
factorsRevalidatedAt | string (date-time) | null | no | — |
newContactMasked | string | null | no | — |
previousContactMasked | string | null | no | — |
recoveryFactorStates | string[] | null | no | — |
resendCount | integer (int32) | no | — |
reverifiedAt | string (date-time) | null | no | — |
status | string | null | no | — |
trustWindowClosesAt | string (date-time) | null | no | — |
trustWindowOpenedAt | string (date-time) | null | no | — |
trustedContactOfRecordMasked | string | null | no | — |
PrincipalValidationDto
| Property | Type | Required | Description |
|---|---|---|---|
exists | boolean | no | — |
homeRegion | string | null | no | — |
isActive | boolean | no | — |
userId | string (uuid) | no | — |
ProbateAssuranceResult
| Property | Type | Required | Description |
|---|---|---|---|
achievedAal | string | null | no | — |
authorityBasis | string | null | no | — |
required | string | null | no | — |
shortfall | string | null | no | — |
ProbateRoleGrantDto
| Property | Type | Required | Description |
|---|---|---|---|
attorneyUserId | string (uuid) | no | — |
estateId | string (uuid) | null | no | — |
expiresAt | string (date-time) | null | no | — |
grantId | string (uuid) | no | — |
jurisdiction | string | null | no | — |
poaId | string (uuid) | null | no | — |
poaType | string | null | no | — |
revokedAt | string (date-time) | null | no | — |
scopeCategoryCount | integer (int32) | no | — |
scopeDocumentCount | integer (int32) | no | — |
scopeFieldCount | integer (int32) | no | — |
status | ProbateRoleStatus | no | — |
ProbateRoleGrantResponse
Response body for the grant call.
| Property | Type | Required | Description |
|---|---|---|---|
grantId | string (uuid) | no | — |
ProbateRoleScopeRequest
Scope counts the grant is bounded to.
| Property | Type | Required | Description |
|---|---|---|---|
categoryCount | integer (int32) | no | — |
documentCount | integer (int32) | no | — |
fieldCount | integer (int32) | no | — |
ProbateRoleStatus
0 | 1 | 2 with no declared properties.
ProbateStepUpChallengeResponse
Wire response for a probate step-up challenge. Exists so `factor` leaves as the published `phone-call`-style string rather than the enum's ordinal — the outbound half of #8134.
| Property | Type | Required | Description |
|---|---|---|---|
deliveryHint | string | null | no | — |
expiresAt | string (date-time) | no | — |
factor | string | null | no | — |
sent | boolean | no | — |
webAuthnChallenge | string | null | no | — |
webAuthnSessionId | string | null | no | — |
ProbateStepUpResponse
Wire response for a successful probate step-up. `authorityBasis` leaves as `court-grant` | `probate-role` — the same vocabulary the token's `authority_basis` claim and the assurance endpoint already publish, rather than the enum's ordinal (#8134).
| Property | Type | Required | Description |
|---|---|---|---|
achievedAal | string | null | no | — |
authorityBasis | string | null | no | — |
estateId | string (uuid) | no | — |
expiresAt | string (date-time) | no | — |
maxExpiresAt | string (date-time) | no | — |
stepUpToken | string | null | no | — |
warnAt | string (date-time) | no | — |
ProblemDetails
| Property | Type | Required | Description |
|---|---|---|---|
detail | string | null | no | — |
instance | string | null | no | — |
status | integer (int32) | null | no | — |
title | string | null | no | — |
type | string | null | no | — |
ProfessionalAdviserAuthorisationResult
| Property | Type | Required | Description |
|---|---|---|---|
adviserUserId | string (uuid) | no | — |
agencyCapabilities | string[] | null | no | — |
agencyId | string (uuid) | null | no | — |
agencyName | string | null | no | — |
authorisedSince | string (date-time) | null | no | — |
caseReference | string | null | no | — |
regulatedBody | string | null | no | — |
verdict | string | null | no | — |
ProfessionalAdviserRegisterResult
| Property | Type | Required | Description |
|---|---|---|---|
adviserCapabilities | string[] | null | no | — |
advisers | ProfessionalAdviserRow[] | null | no | — |
agencyId | string (uuid) | no | — |
agencyName | string | null | no | — |
agencyStatus | string | null | no | — |
authorisedCount | integer (int32) | no | — |
organizationId | string (uuid) | no | — |
totalCount | integer (int32) | no | — |
ProfessionalAdviserRow
| Property | Type | Required | Description |
|---|---|---|---|
adviserReference | string | null | no | — |
adviserUserId | string (uuid) | no | — |
authorised | boolean | no | — |
liveCaseCount | integer (int32) | no | — |
registeredAt | string (date-time) | no | — |
regulatedBody | string | null | no | — |
regulatedReference | string | null | no | — |
revocationReason | string | null | no | — |
revokedAt | string (date-time) | null | no | — |
roleIssuedAt | string (date-time) | null | no | — |
status | string | null | no | — |
suspendedAt | string (date-time) | null | no | — |
suspensionReason | string | null | no | — |
verificationLevel | string | null | no | — |
verifiedAt | string (date-time) | null | no | — |
ProfessionalAttestationDto
| Property | Type | Required | Description |
|---|---|---|---|
assurance | string | null | no | — |
body | string | null | no | — |
credentialType | string | null | no | — |
expiresAtIso | string | null | no | — |
fieldKey | string | null | no | — |
signingKeyId | string | null | no | — |
status | string | null | no | — |
ProfileNameResult
| Property | Type | Required | Description |
|---|---|---|---|
changed | boolean | no | — |
editable | boolean | no | — |
firstName | string | null | no | — |
lastName | string | null | no | — |
ProofingPolicyResult
| Property | Type | Required | Description |
|---|---|---|---|
authority | string | null | no | — |
isDefault | boolean | no | — |
proofingPolicy | string | null | no | — |
subjectUserId | string (uuid) | no | — |
ProofingSessionResult
| Property | Type | Required | Description |
|---|---|---|---|
completedAt | string (date-time) | null | no | — |
expiresAt | string (date-time) | no | — |
failureReason | string | null | no | — |
provider | string | null | no | — |
reachedLevel | string | null | no | — |
relyingServiceId | string | null | no | — |
requiredLevel | string | null | no | — |
satisfiesRequirement | boolean | no | — |
sessionId | string (uuid) | no | — |
shortfallReason | string | null | no | — |
status | string | null | no | — |
subjectUserId | string (uuid) | no | — |
ProveAccountMergeRequest
Wire body to bind proof-of-control for one account: which account, and a second-factor proof enrolled on it. Matches the delivered client's `bindRetiring` payload.
| Property | Type | Required | Description |
|---|---|---|---|
accountId | string (uuid) | null | no | Which account (retiring or surviving) this proof is for. Optional — omit it to prove the session's retiring account, which is what the merge flow's proof step is for. |
factor | string | null | no | The step-up factor name (Totp | Sms | Email | WebAuthn), case-insensitive. |
value | string | null | no | The proof value: an OTP code, or a WebAuthn assertion JSON payload. |
ProveAccountMergeResponse
| Property | Type | Required | Description |
|---|---|---|---|
bothAccountsProven | boolean | no | — |
mergeSessionId | string (uuid) | no | — |
status | string | null | no | — |
ProvisionChildIdentityRequest
New-legal-identity provisioning body.
| Property | Type | Required | Description |
|---|---|---|---|
authorityReference | string | null | no | The order reference the caller believes it is acting under. |
caseReference | string | null | no | The caller's opaque case reference. One case provisions one identity. |
contactEmail | string | null | no | Optional contact address for the new identity. Omit when the child is a minor with no credentials of their own; the principal is then provisioned without a sign-in and credentials are enrolled later. |
passwordHash | string | null | no | Optional client-derived password hash, paired with Essence.Identity.Auth.Api.Controllers.ProvisionChildIdentityRequest.ContactEmail. |
ProvisionChildIdentityResult
| Property | Type | Required | Description |
|---|---|---|---|
alreadyProvisioned | boolean | no | — |
caseReference | string | null | no | — |
credentialsEnrolled | boolean | no | — |
identityRef | string | null | no | — |
provisionedAtIso | string | null | no | — |
provisioningId | string | null | no | — |
RaiseSupportAccessRequestBody
Request body for raising a support-access request — `ImpersonationRequestDraft` in `partner-dashboard/src/features/support-access/types.ts`.
| Property | Type | Required | Description |
|---|---|---|---|
agentId | string (uuid) | no | — |
appId | string (uuid) | no | — |
durationMinutes | integer (int32) | no | — |
reasonCode | string | null | no | — |
scopes | string[] | null | no | — |
subjectUserReference | string | null | no | — |
ticketReference | string | null | no | — |
ReassignAdviserCaseRequest
Request body for handing a case over.
| Property | Type | Required | Description |
|---|---|---|---|
reason | string | null | no | Why the case is moving. |
successorAdviserUserId | string (uuid) | no | The adviser taking the case on. |
ReattestVerifiedNameChangeRequest
Wire body to re-attest the new name.
| Property | Type | Required | Description |
|---|---|---|---|
credentials | NameBearingCredentialInput[] | null | no | Optional: the name-bearing official credentials to reissue under the new name. Carried onto the 9→2 re-attestation event; the cascade is provisioned either way. |
reattestationRef | string | null | no | — |
ReattestVerifiedNameChangeResult
| Property | Type | Required | Description |
|---|---|---|---|
changeId | string (uuid) | no | — |
reattestedAt | string (date-time) | no | — |
status | string | null | no | — |
RecipientContactDto
| Property | Type | Required | Description |
|---|---|---|---|
displayName | string | null | no | — |
email | string | null | no | — |
exists | boolean | no | — |
phone | string | null | no | — |
userId | string (uuid) | no | — |
RecipientLookupRequest
Request body for M:Essence.Identity.Auth.Api.Controllers.RecipientLookupController.Lookup(Essence.Identity.Auth.Api.Controllers.RecipientLookupRequest,System.Threading.CancellationToken).
| Property | Type | Required | Description |
|---|---|---|---|
email | string | null | no | The recipient's email address, as the grantor typed it. |
RecipientResolutionDto
| Property | Type | Required | Description |
|---|---|---|---|
resolved | boolean | no | — |
userId | string (uuid) | null | no | — |
RecogniseAdviceAgencyRequest
Request body for recognising an advice agency.
| Property | Type | Required | Description |
|---|---|---|---|
adviserCapabilities | string[] | null | no | The agency-level adviser permission ceiling. At least one. |
agencyName | string | null | no | Institutional name, e.g. "Citizens Advice Cardiff". |
organizationId | string (uuid) | no | The organisation the recognition attaches to. |
regulatoryBody | string | null | no | The body under whose permission it advises, e.g. `FCA`. |
regulatoryReference | string | null | no | The agency's opaque reference with that body. |
RecogniseSafeguardingAuthorityRequest
Request body for recognising a safeguarding authority.
| Property | Type | Required | Description |
|---|---|---|---|
authorityName | string | null | no | Institutional name, e.g. "Office of the Public Guardian". |
organizationId | string (uuid) | no | The organisation being recognised. |
statutoryReference | string | null | no | Optional reference to the instrument granting the office. |
ReConsentChoiceDto
| Property | Type | Required | Description |
|---|---|---|---|
choice | string | null | no | — |
grantId | string | null | no | — |
RecordAdviserAccreditationRequest
Request body for recording an adviser's professional accreditation.
| Property | Type | Required | Description |
|---|---|---|---|
regulatedBody | string | null | no | The adviser's regulator, e.g. `IMA` or `FCA`. |
regulatedReference | string | null | no | Their opaque reference with that body. |
RecordAssistActionRequest
Wire body for recording a delegate-attributed assist action.
| Property | Type | Required | Description |
|---|---|---|---|
actionType | string | null | no | — |
sessionId | string (uuid) | no | — |
targetRef | string | null | no | — |
touchedKeyMaterial | boolean | no | — |
RecordAssistActionResponse
Response body for the action call.
| Property | Type | Required | Description |
|---|---|---|---|
actionId | string (uuid) | no | — |
sessionId | string (uuid) | no | — |
RecordAssuranceRequest
Body for recording first-run assurance (capability (a)+(b)).
| Property | Type | Required | Description |
|---|---|---|---|
emailVerified | boolean | no | Whether the account's email is verified (the LOA1 precondition). Defaults true. |
invitedByOrg | boolean | no | Whether the account is onboarding under an org invitation. |
orgName | string | null | no | Inviting organisation display name (for the authority label). |
proofingCompleted | boolean | no | Refused when true with 403 `proofing-outcome-not-adjudicated` (#14295): the subject cannot certify its own proofing. Completion is recorded only by a provider-adjudicated proofing session. |
proofingPolicy | string | null | no | Explicit proofing policy (`required`|`deferred`|`optional`); null → per-actor default. |
RecordRecoveryDecisionRequest
Body for recording the first-run recovery decision (debt-2026-07-09-022).
| Property | Type | Required | Description |
|---|---|---|---|
recoverySetUp | boolean | no | True if the holder set up account recovery; false if they deferred it. |
RecordTakeoverProgressRequest
Request body for reporting a completed takeover-recovery step (#7393).
| Property | Type | Required | Description |
|---|---|---|---|
count | integer (int32) | null | no | For `shares-revoked`: how many shares were revoked. |
step | string | null | no | One of `keys-rotated`, `shares-revoked`, `closed`. |
RecordVerificationRequest
Request body for recording an org member verification into the cohort.
| Property | Type | Required | Description |
|---|---|---|---|
checkType | string | null | no | — |
subjectReference | string | null | no | — |
validFrom | string (date-time) | no | — |
validUntil | string (date-time) | no | — |
RecoveryOtpRequestDto
Wire body for `POST /auth/mfa/otp/request`.
| Property | Type | Required | Description |
|---|---|---|---|
action | string | null | no | The step-up action discriminator; must be "recovery-initiate". |
channel | string | null | no | The recovery channel: "email" or "sms". |
RecoveryOtpRequestResponse
Response for a recovery OTP request — mirrors the client's expected shape.
| Property | Type | Required | Description |
|---|---|---|---|
maskedDestination | string | null | no | — |
sent | boolean | no | — |
RecoveryOtpVerifyDto
Wire body for `POST /auth/mfa/otp/verify`.
| Property | Type | Required | Description |
|---|---|---|---|
action | string | null | no | The step-up action discriminator; must be "recovery-initiate". |
channel | string | null | no | The recovery channel: "email" or "sms". |
code | string | null | no | The one-time code the user received. |
RecoveryOtpVerifyResponse
Response for a recovery OTP verify — mirrors the client's `MfaVerifyResponse`.
| Property | Type | Required | Description |
|---|---|---|---|
expiresAt | string (date-time) | null | no | Absolute UTC expiry of StepUpToken. |
stepUpToken | string | null | no | The FR-01.045 `aal=2` / `act=recovery-initiate` elevation token to present as `stepUpToken` on `POST /api/v1/recovery/initiate`. Null when Verified is false (debt-2026-08-24-055 — before this, the surface confirmed the proof and handed back nothing the recovery endpoint could consume). |
verified | boolean | no | Whether the delivered code matched. |
RecoveryPhraseTokenRequest
Request body for `POST /recovery-phrase/token` — the anonymous recovery entry for a user who has forgotten their password. Essence.Identity.Auth.Api.Controllers.RecoveryPhraseTokenRequest.RecoveryProof is the client-derived recovery proof (hex, ≥ 64 chars) — never the phrase.
| Property | Type | Required | Description |
|---|---|---|---|
email | string | null | no | — |
recoveryProof | string | null | no | — |
RecoveryRewrapTokenResponse
Response for `POST /recovery-phrase/token`: the one-shot, 5-minute `purpose=recovery-rewrap` token and its absolute UTC expiry. Carries no key material.
| Property | Type | Required | Description |
|---|---|---|---|
expiresAt | string (date-time) | no | — |
purpose | string | null | no | — |
token | string | null | no | — |
RefreshTokenCommand
| Property | Type | Required | Description |
|---|---|---|---|
deviceFingerprint | string | null | no | — |
ipAddress | string | null | no | — |
refreshToken | string | null | no | — |
RefreshTokenResult
| Property | Type | Required | Description |
|---|---|---|---|
accessToken | string | null | no | — |
accessTokenExpiresAt | string (date-time) | no | — |
refreshToken | string | null | no | — |
refreshTokenExpiresAt | string (date-time) | no | — |
RegenerateMfaBackupCodesResult
| Property | Type | Required | Description |
|---|---|---|---|
backupCodes | string[] | null | no | — |
message | string | null | no | — |
success | boolean | no | — |
RegisterDelegatedAgentRequest
Request body for agent registration.
| Property | Type | Required | Description |
|---|---|---|---|
consentGrantId | string (uuid) | null | no | EPIC 6 grant the agent acts under, when consent-backed. |
grantedScopes | string[] | null | no | Scope slugs the delegation conveys. |
name | string | null | no | Name the principal recognises the agent by. |
organisationId | string (uuid) | null | no | Governing organisation, when there is one. |
RegisterDelegatedAgentResponse
Registration response. The secret appears here and nowhere else, ever.
| Property | Type | Required | Description |
|---|---|---|---|
agentId | string (uuid) | no | The aggregate id. |
agentReference | string | null | no | The opaque cross-service reference. |
secret | string | null | no | The credential secret. Store it now; it cannot be retrieved. |
RegisterOrgInvitationCommand
| Property | Type | Required | Description |
|---|---|---|---|
department | string | null | no | — |
expiresAt | string (date-time) | no | — |
homeRegion | string | null | no | — |
invitationId | string (uuid) | no | — |
invitedByDisplayName | string | null | no | — |
invitedByUserId | string (uuid) | no | — |
inviteeEmail | string | null | no | — |
organizationId | string (uuid) | no | — |
organizationName | string | null | no | — |
preAssignedRoles | PreAssignedRoleInput[] | null | no | — |
requireMfa | boolean | no | — |
requireRecoverySetup | boolean | no | — |
sponsoredPremium | SponsoredPremiumInput | no | — |
token | string | null | no | — |
vaultScope | VaultScopeInput | no | — |
RegisterOrgInvitationResult
| Property | Type | Required | Description |
|---|---|---|---|
alreadyExisted | boolean | no | — |
invitationId | string (uuid) | no | — |
RegisterProfessionalAdviserRequest
Request body for registering an adviser.
| Property | Type | Required | Description |
|---|---|---|---|
adviserReference | string | null | no | Opaque, agency-chosen, non-PII reference (a staff number). |
adviserUserId | string (uuid) | no | The adviser's user-principal id. |
regulatedBody | string | null | no | The adviser's own regulator, when known at registration. |
regulatedReference | string | null | no | Their opaque reference with that regulator. |
RegisterTrustedEhrIssuerRequest
Wire body for registering a trusted EHR issuer.
| Property | Type | Required | Description |
|---|---|---|---|
allowedClientIds | string[] | null | no | SMART app client ids permitted to launch from this issuer. |
displayName | string | null | no | Operator-facing vendor or instance name. |
grantableScopes | string[] | null | no | The ceiling of scopes launches from this issuer may obtain. |
iss | string | null | no | The EHR's FHIR base URL. |
organizationId | string (uuid) | null | no | Owning organisation, when org-scoped. |
RegisterTrustedEhrIssuerResponse
Response to a trusted-issuer registration.
| Property | Type | Required | Description |
|---|---|---|---|
issuerId | string (uuid) | no | Identifier of the registration. |
RegisterUserCommand
| Property | Type | Required | Description |
|---|---|---|---|
breachCheck | string | null | no | — |
deviceFingerprint | string | null | no | — |
deviceType | string | null | no | — |
email | string | null | no | — |
firstName | string | null | no | — |
homeRegion | string | null | no | — |
ipAddress | string | null | no | — |
lastName | string | null | no | — |
passwordHash | string | null | no | — |
passwordPolicyVersion | integer (int32) | null | no | — |
phoneNumber | string | null | no | — |
proofOfWork | SignUpProofOfWork | no | — |
userAgent | string | null | no | — |
RegisterUserResult
| Property | Type | Required | Description |
|---|---|---|---|
accessToken | string | null | no | — |
accessTokenExpiresAt | string (date-time) | no | — |
email | string | null | no | — |
emailVerified | boolean | no | — |
refreshToken | string | null | no | — |
refreshTokenExpiresAt | string (date-time) | no | — |
userId | string (uuid) | no | — |
verificationPending | boolean | no | — |
RegistrationAcceptedResponse
The uniform body of `POST /register` (#7225). There is exactly one value, so a free address and a taken one serialise to the same bytes.
| Property | Type | Required | Description |
|---|---|---|---|
next | string | null | no | The step the caller goes to next: always `verify-email`. |
RemoveExecutorOfficerRequest
Request body for removing an officer from the roster.
| Property | Type | Required | Description |
|---|---|---|---|
reason | string | null | no | Why the officer was removed. Travels with the cascade onto every estate they held, so it is the only explanation a later auditor sees for why those assignments ended. |
RenameWebAuthnCredentialRequest
Request body for renaming a passkey.
| Property | Type | Required | Description |
|---|---|---|---|
name | string | null | no | New user-facing name for the passkey. |
RequestAccountMergeApprovalRequestBody
Wire body to enqueue a merge for org approval (EPIC 7 governance seam, debt-2026-07-09-284): names the organisation whose require-approval policy gates it.
| Property | Type | Required | Description |
|---|---|---|---|
organizationId | string (uuid) | no | The organisation whose require-approval policy gates this merge. |
policyDecision | MergePolicyDecisionInput | no | — |
RequestAccountMergeApprovalResponse
The result of enqueuing a merge for org approval: the merge session, its lifecycle status, its new approval status (`Pending`), and the approving organisation.
| Property | Type | Required | Description |
|---|---|---|---|
approvalStatus | string | null | no | — |
mergeSessionId | string (uuid) | no | — |
organizationId | string (uuid) | no | — |
status | string | null | no | — |
RequestPrimaryContactChangeRequest
Wire body to request a primary-contact change.
| Property | Type | Required | Description |
|---|---|---|---|
affectedConsentRefs | string[] | null | no | Opaque consent-grant references EPIC 6 must re-validate on cutover. |
channel | string | null | no | `Email` or `Phone`. |
currentContact | string | null | no | Plaintext current primary contact — hashed + masked, then discarded. |
newContact | string | null | no | Plaintext new primary contact — hashed + masked, then discarded. |
syncedConnectionRefs | string[] | null | no | Opaque synced-connection references EPIC 19 must repoint on cutover. |
RequestPrimaryContactChangeResult
| Property | Type | Required | Description |
|---|---|---|---|
changeId | string (uuid) | no | — |
newContactMasked | string | null | no | — |
status | string | null | no | — |
RequestVerifiedNameChangeRequest
Wire body to open a verified-name-change.
| Property | Type | Required | Description |
|---|---|---|---|
affectedConsentRefs | string[] | null | no | Opaque consent-grant references EPIC 6 evaluates for the recipient split. |
deedPollDocumentId | string (uuid) | null | no | Optional reference to the deed-poll / legal instrument evidencing the change. Echoed on the change record and carried onto the credential-reissue cascade as its evidence. |
newNameHash | string | null | no | Client-computed SHA-256 hash (lowercase hex) of the NEW verified name. |
newNameMasked | string | null | no | Irreversible masked display hint of the NEW name (e.g. `J••• S•••`). |
previousNameDisposition | string | null | no | `KeepAlias`, `Redact` or `FormerlyKnownAs` (default). |
previousNameHash | string | null | no | Client-computed SHA-256 hash (lowercase hex) of the OLD verified name. |
previousNameMasked | string | null | no | Optional irreversible masked display hint of the PREVIOUS name (e.g. `J••• H•••`), so a surface can state both halves of the change rather than falling back to literals. |
syncedConnectionRefs | string[] | null | no | Opaque synced-connection references EPIC 19 must update on commit. |
RequestVerifiedNameChangeResult
| Property | Type | Required | Description |
|---|---|---|---|
changeId | string (uuid) | no | — |
newNameMasked | string | null | no | — |
previousNameMasked | string | null | no | — |
status | string | null | no | — |
RequiredFactorsResponse
The factors available for step-up for the calling session.
| Property | Type | Required | Description |
|---|---|---|---|
factors | string[] | null | no | — |
ResendEmailVerificationOtpByEmailRequest
Request body for `POST /email/resend-otp/by-email` (#7539).
| Property | Type | Required | Description |
|---|---|---|---|
email | string | null | no | The address to send a fresh verification code to. |
ResendEmailVerificationOtpResult
| Property | Type | Required | Description |
|---|---|---|---|
expiresAt | string (date-time) | null | no | — |
message | string | null | no | — |
sent | boolean | no | — |
ResendKeyClaimCodeResult
| Property | Type | Required | Description |
|---|---|---|---|
challengeId | string (uuid) | no | — |
claimId | string (uuid) | no | — |
resendCount | integer (int32) | no | — |
ResendLoginMfaCodeCommand
| Property | Type | Required | Description |
|---|---|---|---|
challengeToken | string | null | no | — |
ResendLoginMfaCodeResult
| Property | Type | Required | Description |
|---|---|---|---|
message | string | null | no | — |
retryAfterSeconds | integer (int32) | null | no | — |
sent | boolean | no | — |
status | string | null | no | — |
ResendPrimaryContactChallengeRequest
Wire body to resend the challenge (re-supply the new contact).
| Property | Type | Required | Description |
|---|---|---|---|
newContact | string | null | no | — |
ResendPrimaryContactChallengeResult
| Property | Type | Required | Description |
|---|---|---|---|
changeId | string (uuid) | no | — |
resendCount | integer (int32) | no | — |
status | string | null | no | — |
ResolveReturningNationalBootstrapRequest
Request body for a business-admin resolution of a held bootstrap case.
| Property | Type | Required | Description |
|---|---|---|---|
action | string | null | no | — |
creditLevel | string | null | no | — |
note | string | null | no | — |
ReturningNationalReceiptResult
| Property | Type | Required | Description |
|---|---|---|---|
decidedAt | string (date-time) | no | — |
decision | string | null | no | — |
decisionBasis | string | null | no | — |
decisionId | string (uuid) | no | — |
foreignLoa | string | null | no | — |
intakeId | string | null | no | — |
mappedDomesticAssurance | string | null | no | — |
matchedPriorSovereignVaultRef | string | null | no | — |
originJurisdiction | string | null | no | — |
originScheme | string | null | no | — |
policyId | string | null | no | — |
ranIdentityCheck | boolean | no | — |
residualCheckRequired | boolean | no | — |
resolvedAt | string (date-time) | null | no | — |
subjectUserId | string (uuid) | no | — |
RevalidatePrimaryContactFactorsRequest
Wire body to re-validate recovery factors.
| Property | Type | Required | Description |
|---|---|---|---|
factorStates | string[] | null | no | — |
RevalidatePrimaryContactFactorsResult
| Property | Type | Required | Description |
|---|---|---|---|
changeId | string (uuid) | no | — |
factorsRevalidatedAt | string (date-time) | no | — |
recoveryFactorStates | string[] | null | no | — |
status | string | null | no | — |
ReverseMergeResponse
The reversal receipt returned by `POST /api/v1/account/merge/{id}/reverse` — the exact shape the delivered client's `ReverseMergeResult` renders on the Step-7 "Undo merge" affordance (debt-2026-07-07-104).
| Property | Type | Required | Description |
|---|---|---|---|
auditRef | string | null | no | Audit anchor reference for the reversal record (EPIC 4 / 12). |
grantsReverted | integer (int32) | no | Number of repointed grants reverted onto the restored account. |
noticesRetracted | integer (int32) | no | Number of org notices retracted by the reversal. |
restoredAccountId | string (uuid) | no | The account restored by the reversal (previously retired). |
reversedAt | string (date-time) | no | UTC instant the reversal was recorded. |
survivorAccountId | string (uuid) | no | The surviving account retained after the reversal. |
RevocationProofDto
| Property | Type | Required | Description |
|---|---|---|---|
exportable | boolean | no | — |
revocationDateIso | string | null | no | — |
revocationProofRef | string | null | no | — |
revokedGuardianIds | (string (uuid))[] | null | no | — |
subjectId | string (uuid) | no | — |
RevocationSnapshotDto
| Property | Type | Required | Description |
|---|---|---|---|
entries | RevocationSnapshotEntryDto[] | null | no | — |
generatedAt | string (date-time) | no | — |
RevocationSnapshotEntryDto
| Property | Type | Required | Description |
|---|---|---|---|
expiresAt | string (date-time) | no | — |
tokenId | string | null | no | — |
RevokeAllSessionsResult
| Property | Type | Required | Description |
|---|---|---|---|
message | string | null | no | — |
sessionsRevoked | integer (int32) | no | — |
success | boolean | no | — |
RevokeAssistRequestBody
Request body for revoking a grant.
| Property | Type | Required | Description |
|---|---|---|---|
reason | string | null | no | — |
RevokeAssistResult
| Property | Type | Required | Description |
|---|---|---|---|
alreadyRevoked | boolean | no | — |
grantId | string (uuid) | no | — |
RevokeDelegateAccessRequestBody
Request body for revoking a grant.
| Property | Type | Required | Description |
|---|---|---|---|
reason | string | null | no | — |
RevokeDelegateAccessResult
| Property | Type | Required | Description |
|---|---|---|---|
alreadyRevoked | boolean | no | — |
grantId | string (uuid) | no | — |
RevokeProbateRoleRequest
Request body for revoking a grant.
| Property | Type | Required | Description |
|---|---|---|---|
reason | string | null | no | — |
revokedByUserId | string (uuid) | null | no | Optional explicit revoking-party attribution, mirroring Essence.Identity.Auth.Api.Controllers.GrantProbateRoleRequest.GrantedByUserId. Additive and optional: an org-portal caller omits it and keeps attributing to its own claims. |
RevokeProbateRoleResult
| Property | Type | Required | Description |
|---|---|---|---|
grantId | string (uuid) | no | — |
revoked | boolean | no | — |
RevokeSessionResult
| Property | Type | Required | Description |
|---|---|---|---|
message | string | null | no | — |
success | boolean | no | — |
RevokeWearableSessionRequest
Request body for scope-revoking a single lost companion watch's delegated session. The subject is always the authenticated caller (from the JWT), never the body.
| Property | Type | Required | Description |
|---|---|---|---|
delegateFrom | string (uuid) | null | no | The phone principal the watch token was delegated from (FR-65.051); optional. |
reason | string | null | no | Non-PII reason token (e.g. `reported-lost`). Defaults server-side when omitted. |
watchDeviceId | string (uuid) | no | Stable id of the paired watch device to sign out. |
RevokeWearableSessionResult
| Property | Type | Required | Description |
|---|---|---|---|
boundedInertBy | string (date-time) | null | no | — |
revoked | boolean | no | — |
revokedAt | string (date-time) | no | — |
SafeguardingAuthorityRow
| Property | Type | Required | Description |
|---|---|---|---|
authorityId | string (uuid) | no | — |
authorityName | string | null | no | — |
isRecognised | boolean | no | — |
organizationId | string (uuid) | no | — |
recognisedAt | string (date-time) | no | — |
status | string | null | no | — |
statusChangedAt | string (date-time) | no | — |
statusReason | string | null | no | — |
statutoryReference | string | null | no | — |
SafeguardingOfficerAuthorisationResult
| Property | Type | Required | Description |
|---|---|---|---|
authorised | boolean | no | — |
authorisedSince | string (date-time) | null | no | — |
officerUserId | string (uuid) | no | — |
SafeguardingOfficerRegisterResult
| Property | Type | Required | Description |
|---|---|---|---|
authorisedCount | integer (int32) | no | — |
authorityId | string (uuid) | no | — |
authorityName | string | null | no | — |
authorityStatus | string | null | no | — |
officers | SafeguardingOfficerRow[] | null | no | — |
organizationId | string (uuid) | no | — |
totalCount | integer (int32) | no | — |
SafeguardingOfficerRow
| Property | Type | Required | Description |
|---|---|---|---|
authorised | boolean | no | — |
designatedAt | string (date-time) | no | — |
officerReference | string | null | no | — |
officerUserId | string (uuid) | no | — |
revocationReason | string | null | no | — |
revokedAt | string (date-time) | null | no | — |
roleIssuedAt | string (date-time) | null | no | — |
status | string | null | no | — |
suspendedAt | string (date-time) | null | no | — |
suspensionReason | string | null | no | — |
verificationLevel | string | null | no | — |
verifiedAt | string (date-time) | null | no | — |
SendEmailOtpResult
| Property | Type | Required | Description |
|---|---|---|---|
expiresAt | string (date-time) | null | no | — |
message | string | null | no | — |
retryAfterSeconds | integer (int32) | null | no | — |
sent | boolean | no | — |
status | string | null | no | — |
SendProbateStepUpChallengeRequest
Request body for issuing a probate step-up challenge. `factor` carries the contract's kebab-case wire value (`email` | `sms` | `webauthn` | `phone-call` | `postal-code`) — a `string`, not the domain enum, because this service registers no global `JsonStringEnumConverter` and an enum property would bind only integer ordinals (#8134).
| Property | Type | Required | Description |
|---|---|---|---|
estateId | string (uuid) | no | — |
factor | string | null | no | — |
SendSmsOtpResult
| Property | Type | Required | Description |
|---|---|---|---|
expiresAt | string (date-time) | null | no | — |
message | string | null | no | — |
retryAfterSeconds | integer (int32) | null | no | — |
sent | boolean | no | — |
status | string | null | no | — |
SessionDto
| Property | Type | Required | Description |
|---|---|---|---|
accessTokenExpiresAt | string (date-time) | no | — |
createdAt | string (date-time) | no | — |
deviceFriendlyName | string | null | no | — |
deviceId | string (uuid) | no | — |
deviceType | DeviceType | no | — |
id | string (uuid) | no | — |
ipAddress | string | null | no | — |
isActive | boolean | no | — |
isCurrent | boolean | no | — |
lastRefreshAt | string (date-time) | null | no | — |
lastRefreshIpAddress | string | null | no | — |
refreshTokenExpiresAt | string (date-time) | no | — |
status | SessionStatus | no | — |
userAgent | string | null | no | — |
userId | string (uuid) | no | — |
SessionMeResponse
Response DTO for the session identity endpoint.
| Property | Type | Required | Description |
|---|---|---|---|
accessToken | string | null | no | ESS-QA-007 (sovereign-routing reload fix): a fresh SHORT-LIVED access token minted from the cookie-authenticated principal. The SPA holds it in memory only (never persisted) to (a) route data-plane calls to the user's sovereign edge via its `home_region` claim and (b) present a cross-origin bearer to that edge. Null when the account could not be resolved to mint a token (the client then falls back to cookie-only mode). |
accessTokenExpiresAt | string (date-time) | null | no | Absolute expiry (UTC) of Essence.Identity.Auth.Api.Controllers.SessionMeResponse.AccessToken, so the client can proactively re-exchange the cookie for a fresh token before it lapses. |
email | string | null | no | — |
emailVerified | boolean | no | ESS-QA-007 (I-3): whether the account's email is verified. Sourced from the `email_verified` JWT claim. Lets a cookie-mode reload restore the client's `emailVerified` flag so a verified user is not wrongly re-routed to verify-email. |
firstName | string | null | no | — |
hasPassword | boolean | no | True when the account has a client-side password set. False for social/passkey-only accounts. |
homeRegion | string | null | no | The user's home sovereign region (e.g. `GB`) — the routing pointer, non-PII — matching the `home_region` claim on Essence.Identity.Auth.Api.Controllers.SessionMeResponse.AccessToken. Null when no token was minted. |
instanceId | string | null | no | — |
isPasswordless | boolean | no | True when the account has no password but at least one passkey — i.e. it can authenticate without a password. |
lastName | string | null | no | — |
onboardingPending | boolean | no | ESS-QA-007 (I-3): whether first-run onboarding is still pending. Now means "email not yet verified" (computed as `!EmailVerified`) — the only server-sourced onboarding gate a reload must honour. The account setup checklist (password / passkeys / MFA / recovery) reads Essence.Identity.Auth.Api.Controllers.SessionMeResponse.SetupPosture instead, so an email-verified user with an incomplete setup is never re-gated to the onboarding wizard. |
organizationId | string | null | no | The organisation this session is scoped to, resolved from the token's canonical organisation claim (Essence.Platform.Infrastructure.Security.OrgClaims.ClaimNames). `null` means the session has no organisation — a personal account — and nothing else: a token whose aliases disagree is refused by the action rather than reported here as absent (#13852). |
passkeyCount | integer (int32) | no | Number of active WebAuthn/passkey credentials enrolled. |
role | string | null | no | — |
roles | string[] | null | no | Every role the session's token carries, in claim order (#13747). Essence.Identity.Auth.Api.Controllers.SessionMeResponse.Role is only the first of them, so a client that gates on it cannot see a second role: a platform admin who is also granted `identity-authority` was refused the custodial-order console that the server would have served them. Empty for an account with no role. |
setupPosture | SetupPostureDto | no | — |
userId | string | null | no | — |
SessionStatus
0 | 1 | 2 | 3 with no declared properties.
SetAdviceAgencyCapabilitiesRequest
Request body for replacing an agency's adviser permission ceiling.
| Property | Type | Required | Description |
|---|---|---|---|
adviserCapabilities | string[] | null | no | The replacement set. At least one. |
SetOperationalRoleRequest
Request body for a grant. Carries no organisation — that comes from the route.
| Property | Type | Required | Description |
|---|---|---|---|
role | string | null | no | A catalogue role value. |
userId | string (uuid) | no | The member receiving the role. |
SetOrgOperationalRoleOutcome
0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 with no declared properties.
SetOrgOperationalRoleResult
| Property | Type | Required | Description |
|---|---|---|---|
operationalRoles | string[] | null | no | — |
outcome | SetOrgOperationalRoleOutcome | no | — |
SetPasswordRequest
Request body for `POST /password/set`. Essence.Identity.Auth.Api.Controllers.SetPasswordRequest.PasswordHash is the client-derived hash (as on `register`) — never a plaintext password.
| Property | Type | Required | Description |
|---|---|---|---|
passwordHash | string | null | no | — |
SetPreferredLocaleRequest
Body for `PUT /api/v1/users/me/locale` and `PUT /api/v1/profile/preferred-locale`. The subject is resolved from the authenticated principal, never the body.
| Property | Type | Required | Description |
|---|---|---|---|
locale | string | null | no | The requested BCP-47 language tag (e.g. `ar-AE`). |
SetProfileNameRequest
Body for `PUT /api/v1/profile/name`. The subject is resolved from the authenticated principal, never the body.
| Property | Type | Required | Description |
|---|---|---|---|
firstName | string | null | no | The first name. Required. |
lastName | string | null | no | The last name. Optional. |
SetSupportAgentStatusRequestBody
Request body for a bulk agent status change.
| Property | Type | Required | Description |
|---|---|---|---|
agentIds | (string (uuid))[] | null | no | — |
appId | string (uuid) | no | — |
status | string | null | no | — |
SetTrustedEhrIssuerStatusRequest
Wire body for changing a trusted issuer's status.
| Property | Type | Required | Description |
|---|---|---|---|
reason | string | null | no | Operator-supplied reason, recorded for audit. |
status | string | null | no | One of `Active`, `Suspended`, `Withdrawn`. |
SetupPostureDto
Account setup posture nested in Essence.Identity.Auth.Api.Controllers.SessionMeResponse — what the account has configured so the client can render a setup checklist authoritatively (password → `POST /auth/password/set`, passkeys, MFA, recovery).
| Property | Type | Required | Description |
|---|---|---|---|
accountCreatedAt | string (date-time) | null | no | UTC creation timestamp of the account; null when unresolved. |
hasPassword | boolean | no | True when the account has a client-side password set. |
mfaEnabled | boolean | no | True when a second factor (TOTP/SMS/Email) is enrolled. |
passkeyCount | integer (int32) | no | Number of active WebAuthn/passkey credentials enrolled. |
recoveryConfigured | boolean | no | True when a <b>recovery-phrase proof</b> is enrolled on this account (`POST /api/v1/auth/recovery-phrase/enrol`; EPIC 44 D-126 phase 2, FR-05.082) — i.e. the 24-word phrase can recover the vault after a forgotten password. This reflects the recovery PHRASE only. Shamir share configuration (FR-01.096) is owned by the ShamirRecovery module in a different service and is not resolved cross-service here; the client still reads that from `GET /api/v1/recovery/configuration/{userId}`. |
SetUserRoleRequest
Request body for M:Essence.Identity.Auth.Api.Controllers.AdminUserRolesController.GrantRole(System.String,Essence.Identity.Auth.Api.Controllers.SetUserRoleRequest,System.Threading.CancellationToken).
| Property | Type | Required | Description |
|---|---|---|---|
role | string | null | no | — |
SetUserRoleResult
| Property | Type | Required | Description |
|---|---|---|---|
roles | string[] | null | no | — |
userId | string (uuid) | no | — |
SignUpProofOfWork
| Property | Type | Required | Description |
|---|---|---|---|
challenge | string | null | no | — |
solution | string | null | no | — |
SmartTokenExchangeRequest
Wire body for the SMART launch-token exchange.
| Property | Type | Required | Description |
|---|---|---|---|
clientId | string | null | no | The registered SMART app's client id. |
iss | string | null | no | The EHR's FHIR base URL. |
launchToken | string | null | no | The EHR's one-time opaque launch token. |
requestedScopes | string[] | null | no | Explicit scope array; takes precedence over Essence.Identity.Auth.Api.Controllers.SmartTokenExchangeRequest.Scope when present. |
scope | string | null | no | Space-delimited OAuth scope string (the SMART-native shape). |
SmartTokenExchangeResponse
Contracted success body of the SMART launch-token exchange.
| Property | Type | Required | Description |
|---|---|---|---|
accessToken | string | null | no | Scoped FHIR access token, audience-bound to the EHR. |
encounter | string | null | no | Opaque vendor encounter reference (`launch/encounter`), when launched. |
expiresIn | integer (int32) | no | Access-token lifetime in seconds. |
grantedScopes | string[] | null | no | The scopes identity was willing to grant. |
idToken | string | null | no | Clinician identity token, audience-bound to the SMART app. |
patient | string | null | no | Opaque vendor patient reference (`launch/patient`). |
SmsEnrolmentResponse
Text-message codes are on: the masked number they go to, and the backup codes (shown once).
| Property | Type | Required | Description |
|---|---|---|---|
backupCodes | string[] | null | no | — |
enrolled | boolean | no | — |
maskedNumber | string | null | no | — |
SponsoredPremiumInput
| Property | Type | Required | Description |
|---|---|---|---|
entitlementLabel | string | null | no | — |
planLabel | string | null | no | — |
sponsorName | string | null | no | — |
StartAccountMergeRequest
Wire body to start a merge session.
| Property | Type | Required | Description |
|---|---|---|---|
retiredAccountId | string (uuid) | no | The account being retired (folded away). |
retiringAccountIdentifier | string | null | no | The sign-in address naming the account to retire, when its id is unknown. Opens a `PendingBinding` session: the address is resolved and bound at `prove`, after a second factor enrolled on that account verifies — never at open, so opening a session cannot be used to test whether an address holds an Essence account. |
StartAccountMergeResponse
| Property | Type | Required | Description |
|---|---|---|---|
mergeSessionId | string (uuid) | no | — |
status | string | null | no | — |
StartKeyClaimRequestBody
Request body for starting the key claim.
| Property | Type | Required | Description |
|---|---|---|---|
guardianshipId | string (uuid) | null | no | Optional link to the originating guardianship. |
StartKeyClaimResult
| Property | Type | Required | Description |
|---|---|---|---|
challengeId | string (uuid) | no | — |
claimId | string (uuid) | no | — |
requiredAssurance | string | null | no | — |
StepRequest
Body for advancing a session to a coarse step.
| Property | Type | Required | Description |
|---|---|---|---|
step | string | null | no | — |
StepUpAssertionResponse
Wire form of the signed irreversible-action step-up assertion (FR-15.008.7).
| Property | Type | Required | Description |
|---|---|---|---|
action | string | null | no | — |
challengeId | string | null | no | — |
factor | string | null | no | — |
issuedAtUtc | string (date-time) | no | — |
passwordReverified | boolean | no | — |
signature | string | null | no | — |
userId | string (uuid) | no | — |
StepUpEmailCodeRequest
Request body for `POST /api/v1/auth/step-up/email-code` (#8753).
| Property | Type | Required | Description |
|---|---|---|---|
action | string | null | no | The step-up action the code will elevate for, e.g. `password-change`. |
SubjectExportDelegationRequest
Request to mint a subject-export delegation credential for the caller.
| Property | Type | Required | Description |
|---|---|---|---|
exportRequestId | string (uuid) | no | The queued export the credential is bound to. |
lifetimeSeconds | integer (int32) | no | Lifetime the caller's compilation SLA needs. Clamped at mint time to the credential's own ceiling — a caller cannot widen it by asking. |
SubjectExportDelegationResponse
A minted subject-export delegation credential.
| Property | Type | Required | Description |
|---|---|---|---|
expiresAt | string (date-time) | no | Absolute UTC expiry. |
token | string | null | no | The signed JWT to present to subject-export source endpoints. |
tokenId | string | null | no | Its `jti`, for audit correlation. |
SubjectNameabilityDto
| Property | Type | Required | Description |
|---|---|---|---|
exists | boolean | no | — |
hasRecordedName | boolean | no | — |
userId | string (uuid) | no | — |
SubmitAppealByTokenRequest
Body for `POST /api/v1/account/appeals/by-token` — the sessionless appeal.
| Property | Type | Required | Description |
|---|---|---|---|
statement | string | null | no | The appellant's statement. |
token | string | null | no | The single-purpose notice token issued at the sign-in refusal. |
SubmitAppealRequest
Body for `POST /api/v1/account/appeals` (the appellant's statement).
| Property | Type | Required | Description |
|---|---|---|---|
actionId | string (uuid) | no | The account-action decision being appealed. |
statement | string | null | no | The appellant's statement. |
SubmitCustodialOrderRequest
Submission body. Matches the shipped client's `submitOrderProof` payload.
| Property | Type | Required | Description |
|---|---|---|---|
childUserId | string (uuid) | null | no | The child's existing subject id, when custody is being taken of an existing record. |
documentName | string | null | no | — |
documentRef | string | null | no | Opaque reference to the client-encrypted order document, when stored. |
effectiveDate | string | null | no | ISO-8601 date the order took effect. |
evidenceCodes | string[] | null | no | — |
instrumentCode | string | null | no | — |
issuingAuthority | string | null | no | — |
jurisdictionCode | string | null | no | — |
orderReference | string | null | no | — |
SupportAccessCustomerDecisionDto
| Property | Type | Required | Description |
|---|---|---|---|
consentId | string (uuid) | no | — |
decidedAt | string (date-time) | no | — |
expiresAt | string (date-time) | null | no | — |
grantId | string (uuid) | null | no | — |
requestId | string (uuid) | no | — |
status | string | null | no | — |
SupportAccessDecisionBody
The customer's decision — the body `essence-web/src/features/support-access/api/supportAccessApi.ts` already posts.
| Property | Type | Required | Description |
|---|---|---|---|
decision | string | null | no | `allow` or `deny`. |
grantId | string (uuid) | null | no | The grant the caller's own client created, when it did. Verified, not trusted. |
reason | string | null | no | The customer's own words when denying. Never required. |
SupportAccessRequestDto
| Property | Type | Required | Description |
|---|---|---|---|
agentId | string (uuid) | no | — |
durationMinutes | integer (int32) | no | — |
partnerAppId | string (uuid) | no | — |
raisedAt | string (date-time) | no | — |
requestId | string (uuid) | no | — |
scopes | string[] | null | no | — |
status | string | null | no | — |
SupportAccessRequestListItemDto
| Property | Type | Required | Description |
|---|---|---|---|
agentId | string (uuid) | no | — |
agentPrincipalId | string (uuid) | no | — |
consentId | string (uuid) | null | no | — |
decidedAt | string (date-time) | null | no | — |
declineReasonCode | string | null | no | — |
durationMinutes | integer (int32) | no | — |
grantId | string (uuid) | null | no | — |
partnerAppId | string (uuid) | no | — |
raisedAt | string (date-time) | no | — |
raisedByUserId | string (uuid) | no | — |
reasonCode | string | null | no | — |
requestId | string (uuid) | no | — |
scopes | string[] | null | no | — |
status | string | null | no | — |
subjectUserReference | string | null | no | — |
supervisorAgentId | string (uuid) | null | no | — |
supervisorDecidedAt | string (date-time) | null | no | — |
supervisorPrincipalId | string (uuid) | null | no | — |
ticketReference | string | null | no | — |
SupportAccessRequestListItemDtoCursorResult
| Property | Type | Required | Description |
|---|---|---|---|
hasMore | boolean | no | — |
items | SupportAccessRequestListItemDto[] | null | no | — |
nextCursor | string | null | no | — |
pageSize | integer (int32) | no | — |
previousCursor | string | null | no | — |
SupportAccessSessionDescriptorDto
| Property | Type | Required | Description |
|---|---|---|---|
agentDisplayName | string | null | no | — |
agentPrincipalId | string (uuid) | no | — |
consentId | string (uuid) | no | — |
partnerAppId | string (uuid) | no | — |
partnerName | string | null | no | — |
partnerNameStatus | string | null | no | — |
publisherName | string | null | no | — |
publisherVerified | boolean | null | no | — |
reasonCode | string | null | no | — |
ticketReference | string | null | no | — |
SupportAgentDto
| Property | Type | Required | Description |
|---|---|---|---|
agentId | string (uuid) | no | — |
displayName | string | null | no | — |
email | string | null | no | — |
enrolledAt | string (date-time) | no | — |
principalId | string (uuid) | null | no | — |
role | string | null | no | — |
status | string | null | no | — |
SupportAgentInvitationDto
| Property | Type | Required | Description |
|---|---|---|---|
acceptedAt | string (date-time) | null | no | — |
agentId | string (uuid) | no | — |
displayName | string | null | no | — |
email | string | null | no | — |
invitedAt | string (date-time) | no | — |
partnerAppId | string (uuid) | no | — |
partnerAppName | string | null | no | — |
partnerNameStatus | string | null | no | — |
publisherName | string | null | no | — |
publisherVerified | boolean | null | no | — |
role | string | null | no | — |
status | string | null | no | — |
SupportAgentStatusChangeDto
| Property | Type | Required | Description |
|---|---|---|---|
updated | integer (int32) | no | — |
SupportImpersonationPolicyDto
| Property | Type | Required | Description |
|---|---|---|---|
allowedScopes | string[] | null | no | — |
appId | string (uuid) | no | — |
configured | boolean | no | — |
dailyRequestLimitPerAgent | integer (int32) | no | — |
dualApprovalRequired | boolean | no | — |
eligibleRoles | string[] | null | no | — |
maxDurationMinutes | integer (int32) | no | — |
reasonCodes | string[] | null | no | — |
updatedAt | string (date-time) | null | no | — |
SupportImpersonationPolicyRequestBody
Request body for saving a support-impersonation policy (the dashboard's `ImpersonationPolicy`).
| Property | Type | Required | Description |
|---|---|---|---|
allowedScopes | string[] | null | no | — |
appId | string (uuid) | no | — |
dailyRequestLimitPerAgent | integer (int32) | no | — |
dualApprovalRequired | boolean | no | — |
eligibleRoles | string[] | null | no | — |
maxDurationMinutes | integer (int32) | no | — |
reasonCodes | string[] | null | no | — |
SuspendDelegatedAgentRequest
Request body for incident-driven suspension.
| Property | Type | Required | Description |
|---|---|---|---|
incidentId | string (uuid) | no | The EPIC 12 incident driving containment. |
reason | string | null | no | A closed-vocabulary suspension reason. |
SuspendDelegatedAgentResponse
Suspension response — the EPIC 9 containment leg's return value.
| Property | Type | Required | Description |
|---|---|---|---|
sessionsRevoked | integer (int32) | no | How many live sessions were cut. |
suspensionReference | string | null | no | The reference the containment chain records. |
wasAlreadySuspended | boolean | no | True when the agent's access had already been cut. |
TakeoverIncidentView
| Property | Type | Required | Description |
|---|---|---|---|
incidentId | string (uuid) | no | — |
keysRotatedAt | string (date-time) | null | no | — |
openedAt | string (date-time) | no | — |
sessionsTerminated | integer (int32) | no | — |
sharesRevokedAt | string (date-time) | null | no | — |
sharesRevokedCount | integer (int32) | no | — |
TakeoverStateView
| Property | Type | Required | Description |
|---|---|---|---|
frozen | boolean | no | — |
frozenAt | string (date-time) | null | no | — |
incident | TakeoverIncidentView | no | — |
TerminatePrincipalAccessRequest
Request body for an FR-09.044 administrative access termination. The acting operator is deliberately absent — it comes from the caller's token.
| Property | Type | Required | Description |
|---|---|---|---|
campaignRef | string | null | no | The recertification campaign this termination is anchored to. Required. |
deviceId | string (uuid) | null | no | Required when Essence.Identity.Auth.Api.Controllers.TerminatePrincipalAccessRequest.Scope is `device`. |
grantId | string (uuid) | null | no | The access grant being revoked, if the campaign named one. |
reason | string | null | no | Non-PII reason token (e.g. `recertification-deadline-unattested`). Required. |
scope | string | null | no | `all` (default), `device`, or `sessions`. |
sessionIds | (string (uuid))[] | null | no | Required when Essence.Identity.Auth.Api.Controllers.TerminatePrincipalAccessRequest.Scope is `sessions`. |
subjectUserId | string (uuid) | no | The staff principal whose access is being terminated. |
systemCode | string | null | no | The EPIC 87 access-bearing system code the revocation is on behalf of, if named. |
TerminatePrincipalAccessResult
| Property | Type | Required | Description |
|---|---|---|---|
credentialsRevoked | integer (int32) | no | — |
recordId | string (uuid) | null | no | — |
refusedReason | string | null | no | — |
sessionsRevoked | integer (int32) | no | — |
terminated | boolean | no | — |
terminatedAt | string (date-time) | null | no | — |
TerminateSupportAccessSessionRequestBody
Request body for a partner force-terminate.
| Property | Type | Required | Description |
|---|---|---|---|
reason | string | null | no | — |
TerminateSupportAccessSessionResult
| Property | Type | Required | Description |
|---|---|---|---|
alreadyEnded | boolean | no | — |
sessionId | string (uuid) | no | — |
TokenValidationDto
| Property | Type | Required | Description |
|---|---|---|---|
deviceId | string (uuid) | null | no | — |
email | string | null | no | — |
emailVerified | boolean | no | — |
errorMessage | string | null | no | — |
isValid | boolean | no | — |
mfaEnabled | boolean | no | — |
userId | string (uuid) | null | no | — |
TransitionAuditResultDto
| Property | Type | Required | Description |
|---|---|---|---|
auditRecordId | string | null | no | — |
recordedAtIso | string | null | no | — |
TransitionGuardianshipRequest
Request body for committing the majority transition.
| Property | Type | Required | Description |
|---|---|---|---|
reConsentDecisions | ReConsentChoiceDto[] | null | no | The young adult's per-grant re-consent decisions from the affirmative gate. |
TrustDeviceResult
| Property | Type | Required | Description |
|---|---|---|---|
message | string | null | no | — |
success | boolean | no | — |
TrustedEhrIssuerDto
| Property | Type | Required | Description |
|---|---|---|---|
allowedClientIds | string[] | null | no | — |
displayName | string | null | no | — |
distrustReason | string | null | no | — |
distrustedAt | string (date-time) | null | no | — |
grantableScopes | string[] | null | no | — |
id | string (uuid) | no | — |
iss | string | null | no | — |
organizationId | string (uuid) | null | no | — |
status | string | null | no | — |
UaePassAccountLinkRequest
Body of `POST auth/federated-accounts/uae-pass`.
| Property | Type | Required | Description |
|---|---|---|---|
homeRegion | string | null | no | The sovereign region a new account is homed in (the caller's, `AE`). |
subject | string | null | no | The verified UAE Pass `sub`. |
UaePassAccountLinkResponse
Response of `POST auth/federated-accounts/uae-pass`.
| Property | Type | Required | Description |
|---|---|---|---|
isNewUser | boolean | no | True when this call provisioned the account. |
userId | string (uuid) | no | The Essence user id the subject is linked to. |
UndoAccountMergeResponse
| Property | Type | Required | Description |
|---|---|---|---|
mergeSessionId | string (uuid) | no | — |
reversedAt | string (date-time) | no | — |
status | string | null | no | — |
UnlockAccountResult
| Property | Type | Required | Description |
|---|---|---|---|
message | string | null | no | — |
success | boolean | no | — |
userNotFound | boolean | no | — |
UpdateDeviceNameRequest
| Property | Type | Required | Description |
|---|---|---|---|
friendlyName | string | null | no | — |
UpdateDeviceNameResult
| Property | Type | Required | Description |
|---|---|---|---|
message | string | null | no | — |
success | boolean | no | — |
UserIdentityAttributesDto
| Property | Type | Required | Description |
|---|---|---|---|
email | string | null | no | — |
emailVerified | boolean | no | — |
exists | boolean | no | — |
firstName | string | null | no | — |
lastName | string | null | no | — |
nameAssured | boolean | no | — |
phone | string | null | no | — |
phoneVerified | boolean | no | — |
userId | string (uuid) | no | — |
ValidateTokenQuery
| Property | Type | Required | Description |
|---|---|---|---|
accessToken | string | null | no | — |
VaultScopeInput
| Property | Type | Required | Description |
|---|---|---|---|
access | string | null | no | — |
description | string | null | no | — |
vaultLabel | string | null | no | — |
VerificationActionResult
| Property | Type | Required | Description |
|---|---|---|---|
applied | integer (int32) | no | — |
appliedVerificationIds | (string (uuid))[] | null | no | — |
requested | integer (int32) | no | — |
VerificationIdsRequest
Request body carrying the target verification ids for a bulk recheck / reminder.
| Property | Type | Required | Description |
|---|---|---|---|
verificationIds | (string (uuid))[] | null | no | — |
VerifiedNameChangeView
| Property | Type | Required | Description |
|---|---|---|---|
accountId | string (uuid) | no | — |
affectedConsentRefs | string[] | null | no | — |
auditAnchorRef | string | null | no | — |
cancelledAt | string (date-time) | null | no | — |
changeId | string (uuid) | no | — |
committedAt | string (date-time) | null | no | — |
deedPollDocumentId | string (uuid) | null | no | — |
newNameHash | string | null | no | — |
newNameMasked | string | null | no | — |
notifiedCount | integer (int32) | no | — |
previousNameDisposition | string | null | no | — |
previousNameHash | string | null | no | — |
previousNameMasked | string | null | no | — |
reattestationRef | string | null | no | — |
reattestedAt | string (date-time) | null | no | — |
status | string | null | no | — |
syncedConnectionRefs | string[] | null | no | — |
withheldCount | integer (int32) | no | — |
VerifyEmailOtpByEmailRequest
Request body for `POST /email/verify-otp/by-email` (#7539) — the sessionless redemption. Carries the address because an anonymous caller has nothing else to identify itself with.
| Property | Type | Required | Description |
|---|---|---|---|
code | string | null | no | The 6-digit code from the verification email. |
email | string | null | no | The address the account was registered with. |
VerifyEmailOtpByEmailResponse
Response body for a successful `POST /email/verify-otp/by-email`.
| Property | Type | Required | Description |
|---|---|---|---|
verified | boolean | no | Always true when this body is returned. |
VerifyEmailOtpRequest
Request body for `POST /email/verify-otp` — the in-app email-verification OTP the user typed into the app.
| Property | Type | Required | Description |
|---|---|---|---|
code | string | null | no | — |
VerifyEmailOtpResult
| Property | Type | Required | Description |
|---|---|---|---|
accessToken | string | null | no | — |
accessTokenExpiresAt | string (date-time) | null | no | — |
attemptsExhausted | boolean | no | — |
codeExpired | boolean | no | — |
message | string | null | no | — |
refreshToken | string | null | no | — |
refreshTokenExpiresAt | string (date-time) | null | no | — |
verified | boolean | no | — |
VerifyEmailResult
| Property | Type | Required | Description |
|---|---|---|---|
userId | string (uuid) | null | no | — |
verified | boolean | no | — |
VerifyExecutorOfficerRequest
Request body for recording an officer's identity verification.
| Property | Type | Required | Description |
|---|---|---|---|
verificationLevel | string | null | no | The assurance level reached (e.g. `medium`, `high`). |
verificationReference | string | null | no | Non-PII reference to the identity-assurance record that verified the officer. |
VerifyKeyClaimRequestBody
Request body for verifying the key claim.
| Property | Type | Required | Description |
|---|---|---|---|
code | string | null | no | The one-time code the subject received. |
rewrappedVaultKeyEnvelope | string | null | no | The device-produced re-wrapped vault UMK envelope (private half never leaves the device). |
VerifyKeyClaimResult
| Property | Type | Required | Description |
|---|---|---|---|
claimId | string (uuid) | no | — |
identityChangeRef | string | null | no | — |
remainingAttempts | integer (int32) | no | — |
revocationProofRef | string | null | no | — |
verified | boolean | no | — |
verifiedAtIso | string | null | no | — |
VerifyMfaCommand
| Property | Type | Required | Description |
|---|---|---|---|
allowWhenMfaDisabled | boolean | no | — |
code | string | null | no | — |
method | MfaMethod | no | — |
userId | string (uuid) | no | — |
VerifyMfaResult
| Property | Type | Required | Description |
|---|---|---|---|
isValid | boolean | no | — |
message | string | null | no | — |
success | boolean | no | — |
VerifyNewPrimaryContactAddressRequest
Wire body to verify the new address.
| Property | Type | Required | Description |
|---|---|---|---|
code | string | null | no | — |
VerifyNewPrimaryContactAddressResult
| Property | Type | Required | Description |
|---|---|---|---|
changeId | string (uuid) | no | — |
status | string | null | no | — |
trustWindowClosesAt | string (date-time) | no | — |
VerifyProfessionalAdviserRequest
Request body for recording an adviser's identity verification.
| Property | Type | Required | Description |
|---|---|---|---|
verificationLevel | string | null | no | The assurance level reached, e.g. `high`. |
verificationReference | string | null | no | Non-PII reference to the identity-assurance record. |
VerifySafeguardingOfficerRequest
Request body for recording an officer's identity verification.
| Property | Type | Required | Description |
|---|---|---|---|
verificationLevel | string | null | no | The assurance level reached, e.g. `high`. |
verificationReference | string | null | no | Non-PII reference to the identity-assurance record. |
WebAuthnAuthenticationOptions
| Property | Type | Required | Description |
|---|---|---|---|
allowCredentials | WebAuthnCredentialDescriptor[] | null | no | — |
challenge | string | null | no | — |
rpId | string | null | no | — |
sessionId | string | null | no | — |
timeout | integer (int32) | no | — |
userVerification | string | null | no | — |
WebAuthnAuthenticationResult
| Property | Type | Required | Description |
|---|---|---|---|
accessToken | string | null | no | — |
deviceLimit | DeviceLimitPause | no | — |
deviceLimitReached | boolean | no | — |
errorMessage | string | null | no | — |
expiresIn | integer (int32) | no | — |
mfaRequired | boolean | no | — |
refreshToken | string | null | no | — |
success | boolean | no | — |
userId | string (uuid) | no | — |
WebAuthnAuthenticatorSelection
| Property | Type | Required | Description |
|---|---|---|---|
authenticatorAttachment | string | null | no | — |
requireResidentKey | boolean | no | — |
residentKey | string | null | no | — |
userVerification | string | null | no | — |
WebAuthnCredentialDescriptor
| Property | Type | Required | Description |
|---|---|---|---|
id | string | null | no | — |
transports | string[] | null | no | — |
type | string | null | no | — |
WebAuthnCredentialListResponse
Envelope for the passkey list, matching the client's `{ data: [...] }` shape.
| Property | Type | Required | Description |
|---|---|---|---|
data | WebAuthnCredentialSummary[] | null | no | — |
WebAuthnCredentialSummary
| Property | Type | Required | Description |
|---|---|---|---|
aaguid | string | null | no | — |
authenticatorModel | string | null | no | — |
certification | string | null | no | — |
certificationWithdrawnReason | string | null | no | — |
createdAt | string (date-time) | no | — |
id | string | null | no | — |
lastUsed | string (date-time) | null | no | — |
name | string | null | no | — |
transports | string[] | null | no | — |
type | string | null | no | — |
webAuthnCredentialId | string | null | no | — |
WebAuthnPubKeyCredParam
| Property | Type | Required | Description |
|---|---|---|---|
alg | integer (int32) | no | — |
type | string | null | no | — |
WebAuthnRegistrationOptions
| Property | Type | Required | Description |
|---|---|---|---|
attestation | string | null | no | — |
authenticatorSelection | WebAuthnAuthenticatorSelection | no | — |
challenge | string | null | no | — |
excludeCredentials | WebAuthnCredentialDescriptor[] | null | no | — |
pubKeyCredParams | WebAuthnPubKeyCredParam[] | null | no | — |
relyingParty | WebAuthnRelyingParty | no | — |
sessionId | string | null | no | — |
timeout | integer (int32) | no | — |
user | WebAuthnUserEntity | no | — |
WebAuthnRegistrationResult
| Property | Type | Required | Description |
|---|---|---|---|
createdAt | string (date-time) | no | — |
credentialId | string (uuid) | no | — |
credentialType | string | null | no | — |
deviceName | string | null | no | — |
errorMessage | string | null | no | — |
success | boolean | no | — |
vaultBindingToken | string | null | no | — |
WebAuthnRelyingParty
| Property | Type | Required | Description |
|---|---|---|---|
id | string | null | no | — |
name | string | null | no | — |
WebAuthnUserEntity
| Property | Type | Required | Description |
|---|---|---|---|
displayName | string | null | no | — |
id | string | null | no | — |
name | string | null | no | — |
WithdrawAccountMergeApprovalResponse
The result of retracting a queued approval request (gap G-withdraw, `uxf-2026-08-12-017`): the merge session and the approval state the SERVER now holds. Exactly the two fields the member's client reads before releasing its override — it branches on this outcome rather than on anything it stored locally.
| Property | Type | Required | Description |
|---|---|---|---|
approvalStatus | string | null | no | — |
mergeSessionId | string (uuid) | no | — |