{
"components": {
"schemas": {
"AcceptInvitationAsMemberResult": {
"additionalProperties": false,
"properties": {
"accessToken": {
"nullable": true,
"type": "string"
},
"accessTokenExpiresAt": {
"format": "date-time",
"type": "string"
},
"invitationId": {
"format": "uuid",
"type": "string"
},
"organizationId": {
"format": "uuid",
"type": "string"
},
"sponsoredEntitlementGranted": {
"type": "boolean"
}
},
"type": "object"
},
"AcceptInvitationCommand": {
"additionalProperties": false,
"properties": {
"deviceFingerprint": {
"nullable": true,
"type": "string"
},
"deviceType": {
"nullable": true,
"type": "string"
},
"firstName": {
"nullable": true,
"type": "string"
},
"ipAddress": {
"nullable": true,
"type": "string"
},
"lastName": {
"nullable": true,
"type": "string"
},
"passwordHash": {
"nullable": true,
"type": "string"
},
"token": {
"nullable": true,
"type": "string"
},
"userAgent": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"AcceptInvitationResult": {
"additionalProperties": false,
"properties": {
"accessToken": {
"nullable": true,
"type": "string"
},
"accessTokenExpiresAt": {
"format": "date-time",
"type": "string"
},
"homeRegion": {
"nullable": true,
"type": "string"
},
"organizationId": {
"format": "uuid",
"type": "string"
},
"refreshToken": {
"nullable": true,
"type": "string"
},
"refreshTokenExpiresAt": {
"format": "date-time",
"type": "string"
},
"sponsoredEntitlementGranted": {
"type": "boolean"
},
"userId": {
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"AccountActionNoticeDto": {
"additionalProperties": false,
"properties": {
"action": {
"nullable": true,
"type": "string"
},
"actionId": {
"format": "uuid",
"type": "string"
},
"appealCaseRef": {
"nullable": true,
"type": "string"
},
"appealable": {
"type": "boolean"
},
"duration": {
"nullable": true,
"type": "string"
},
"effectiveAt": {
"format": "date-time",
"type": "string"
},
"policyClause": {
"nullable": true,
"type": "string"
},
"reasonCategory": {
"nullable": true,
"type": "string"
},
"scope": {
"nullable": true,
"type": "string"
},
"status": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"AccountClosureCancelRequest": {
"additionalProperties": false,
"description": "The two values the closure alert's link carries.",
"properties": {
"closureId": {
"description": "The closure (the closure event's id).",
"format": "uuid",
"type": "string"
},
"token": {
"description": "The link's single-use token.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"AccountClosureCancelResponse": {
"additionalProperties": false,
"description": "A live link was used: the closure is cancelled and the account is open.",
"properties": {
"cancelled": {
"type": "boolean"
}
},
"type": "object"
},
"AccountClosureDecisionResult": {
"additionalProperties": false,
"properties": {
"accountId": {
"format": "uuid",
"type": "string"
},
"appealRoute": {
"nullable": true,
"type": "string"
},
"approvedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"approvedBy": {
"format": "uuid",
"nullable": true,
"type": "string"
},
"cause": {
"nullable": true,
"type": "string"
},
"closureEventId": {
"format": "uuid",
"nullable": true,
"type": "string"
},
"decidedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"decidedBy": {
"format": "uuid",
"nullable": true,
"type": "string"
},
"decisionId": {
"format": "uuid",
"type": "string"
},
"evidenceReference": {
"nullable": true,
"type": "string"
},
"openedAt": {
"format": "date-time",
"type": "string"
},
"reasonCategory": {
"nullable": true,
"type": "string"
},
"reference": {
"nullable": true,
"type": "string"
},
"rejectedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"rejectedBy": {
"format": "uuid",
"nullable": true,
"type": "string"
},
"shredNotBefore": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"status": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"AccountFactorHoldView": {
"additionalProperties": false,
"description": "A hold on the caller's text-message factor, as the holder sees it. No number, ids and instants only.",
"properties": {
"canConfirmHere": {
"description": "Whether this session may end it now.",
"type": "boolean"
},
"event": {
"description": "The change the operator attested: `sim_swap`, `esim_reprovision`, `port_out` or `port_in`.",
"nullable": true,
"type": "string"
},
"factor": {
"description": "`sms`.",
"nullable": true,
"type": "string"
},
"heldUntil": {
"description": "When it lapses unless ended earlier (UTC).",
"format": "date-time",
"type": "string"
},
"holdId": {
"description": "The hold.",
"format": "uuid",
"type": "string"
},
"placedAt": {
"description": "When it came into force (UTC).",
"format": "date-time",
"type": "string"
},
"releasePath": {
"description": "How it ended, if it has.",
"nullable": true,
"type": "string"
},
"releasePaths": {
"description": "How it can end.",
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
},
"releasedAt": {
"description": "When it ended (UTC), if it has.",
"format": "date-time",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"AccountMergeGovernanceResult": {
"additionalProperties": false,
"properties": {
"mode": {
"nullable": true,
"type": "string"
},
"orgName": {
"nullable": true,
"type": "string"
},
"reason": {
"nullable": true,
"type": "string"
},
"resolution": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"AccountMergeReversibilityResult": {
"additionalProperties": false,
"properties": {
"posture": {
"nullable": true,
"type": "string"
},
"windowDays": {
"format": "int32",
"nullable": true,
"type": "integer"
}
},
"type": "object"
},
"AccountMergeStatusResult": {
"additionalProperties": false,
"properties": {
"committedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"mergeSessionId": {
"format": "uuid",
"type": "string"
},
"reversedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"reversibleUntil": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"stages": {
"items": {
"$ref": "#/components/schemas/MergeStageProgressDto"
},
"nullable": true,
"type": "array"
},
"status": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"ActingAsContextDto": {
"additionalProperties": false,
"properties": {
"capabilities": {
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
},
"delegationId": {
"format": "uuid",
"type": "string"
},
"expiresAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"grantId": {
"format": "uuid",
"type": "string"
},
"isActive": {
"type": "boolean"
},
"principalUserId": {
"format": "uuid",
"type": "string"
},
"revokedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"surface": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"ActiveDeviceSummary": {
"additionalProperties": false,
"properties": {
"deviceId": {
"format": "uuid",
"type": "string"
},
"deviceType": {
"nullable": true,
"type": "string"
},
"lastUsedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"name": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"ActiveProbateRoleResult": {
"additionalProperties": false,
"properties": {
"grantId": {
"format": "uuid",
"nullable": true,
"type": "string"
},
"hasActiveGrant": {
"type": "boolean"
}
},
"type": "object"
},
"AddExecutorOfficerRequest": {
"additionalProperties": false,
"description": "Request body for adding an individual to the executor roster.",
"properties": {
"officerReference": {
"description": "Optional opaque, org-chosen, non-PII reference (e.g. a staff number).",
"nullable": true,
"type": "string"
},
"officerUserId": {
"description": "The officer's user-principal id.",
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"AdminUserPageDto": {
"additionalProperties": false,
"properties": {
"items": {
"items": {
"$ref": "#/components/schemas/AdminUserSummaryDto"
},
"nullable": true,
"type": "array"
},
"page": {
"format": "int32",
"type": "integer"
},
"pageSize": {
"format": "int32",
"type": "integer"
},
"totalCount": {
"format": "int32",
"type": "integer"
}
},
"type": "object"
},
"AdminUserSummaryDto": {
"additionalProperties": false,
"properties": {
"administrativeStatus": {
"nullable": true,
"type": "string"
},
"createdAt": {
"format": "date-time",
"type": "string"
},
"currentAccountActionId": {
"format": "uuid",
"nullable": true,
"type": "string"
},
"email": {
"nullable": true,
"type": "string"
},
"emailVerified": {
"type": "boolean"
},
"failedLoginAttempts": {
"format": "int32",
"type": "integer"
},
"firstName": {
"nullable": true,
"type": "string"
},
"homeRegion": {
"nullable": true,
"type": "string"
},
"isActive": {
"type": "boolean"
},
"lastLoginAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"lastName": {
"nullable": true,
"type": "string"
},
"lockoutEndAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"mfaEnabled": {
"type": "boolean"
},
"phoneVerified": {
"type": "boolean"
},
"preferredLocale": {
"nullable": true,
"type": "string"
},
"roles": {
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
},
"userId": {
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"AdviceAgencyRow": {
"additionalProperties": false,
"properties": {
"adviserCapabilities": {
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
},
"agencyId": {
"format": "uuid",
"type": "string"
},
"agencyName": {
"nullable": true,
"type": "string"
},
"isRecognised": {
"type": "boolean"
},
"organizationId": {
"format": "uuid",
"type": "string"
},
"recognisedAt": {
"format": "date-time",
"type": "string"
},
"regulatoryBody": {
"nullable": true,
"type": "string"
},
"regulatoryReference": {
"nullable": true,
"type": "string"
},
"status": {
"nullable": true,
"type": "string"
},
"statusChangedAt": {
"format": "date-time",
"type": "string"
},
"statusReason": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"AdviserCaseAssignmentRow": {
"additionalProperties": false,
"properties": {
"adviserUserId": {
"format": "uuid",
"type": "string"
},
"assignedAt": {
"format": "date-time",
"type": "string"
},
"assignedByUserId": {
"format": "uuid",
"type": "string"
},
"assignmentId": {
"format": "uuid",
"type": "string"
},
"caseReference": {
"nullable": true,
"type": "string"
},
"clientUserId": {
"format": "uuid",
"type": "string"
},
"endReason": {
"nullable": true,
"type": "string"
},
"endedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"endedByUserId": {
"format": "uuid",
"nullable": true,
"type": "string"
},
"isLive": {
"type": "boolean"
},
"reassignedToAdviserUserId": {
"format": "uuid",
"nullable": true,
"type": "string"
},
"status": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"AdviserCaseloadResult": {
"additionalProperties": false,
"properties": {
"agencyId": {
"format": "uuid",
"type": "string"
},
"assignments": {
"items": {
"$ref": "#/components/schemas/AdviserCaseAssignmentRow"
},
"nullable": true,
"type": "array"
},
"liveCount": {
"format": "int32",
"type": "integer"
},
"totalCount": {
"format": "int32",
"type": "integer"
}
},
"type": "object"
},
"AgentKeyResponse": {
"additionalProperties": false,
"description": "Result of registering an agent key.",
"properties": {
"agentReference": {
"description": "The agent.",
"nullable": true,
"type": "string"
},
"replaced": {
"description": "True when an earlier key was replaced.",
"type": "boolean"
},
"thumbprint": {
"description": "RFC 7638 thumbprint — the `cnf.jkt` the agent's tokens now carry.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"AgentPublicJwkRequest": {
"additionalProperties": {},
"description": "Body of `PUT …/{agentReference}/key`: one EC P-256 public JWK. Every member other than\r\nthe four declared lands in Essence.Identity.Auth.Api.Controllers.AgentPublicJwkRequest.AdditionalMembers so it can be refused by name.",
"properties": {
"crv": {
"description": "Curve — must be `P-256`.",
"nullable": true,
"type": "string"
},
"kty": {
"description": "Key type — must be `EC`.",
"nullable": true,
"type": "string"
},
"x": {
"description": "x coordinate, base64url.",
"nullable": true,
"type": "string"
},
"y": {
"description": "y coordinate, base64url.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"AgentTokenRequest": {
"additionalProperties": false,
"description": "Request body for an agent token exchange.",
"properties": {
"agentReference": {
"description": "The agent's opaque reference.",
"nullable": true,
"type": "string"
},
"secret": {
"description": "The credential secret.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"AgentTokenResponse": {
"additionalProperties": false,
"description": "An issued agent session.",
"properties": {
"expiresAt": {
"description": "When it expires (the token's `exp`).",
"format": "date-time",
"type": "string"
},
"sessionToken": {
"description": "The agent access token — a platform JWT since AG-D1 (it was an opaque secret before). The\r\nfield keeps its name so existing callers need no change.",
"nullable": true,
"type": "string"
},
"tokenType": {
"description": "How to present Essence.Identity.Auth.Api.Controllers.AgentTokenResponse.SessionToken: always `Bearer` (CONTRACTS §2).",
"nullable": true,
"readOnly": true,
"type": "string"
}
},
"type": "object"
},
"AnswerOutOfBandProofChallengeResult": {
"additionalProperties": false,
"properties": {
"attemptsRemaining": {
"format": "int32",
"type": "integer"
},
"challengeId": {
"format": "uuid",
"type": "string"
},
"outcome": {
"$ref": "#/components/schemas/OutOfBandProofOutcome"
},
"proven": {
"type": "boolean"
}
},
"type": "object"
},
"AnswerProofChallengeRequest": {
"additionalProperties": false,
"description": "Answer request.",
"properties": {
"code": {
"description": "The one-time code as delivered to the account's own recovery address.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"AppealCaseDto": {
"additionalProperties": false,
"properties": {
"caseRef": {
"nullable": true,
"type": "string"
},
"expectedResponseBy": {
"format": "date-time",
"type": "string"
},
"status": {
"nullable": true,
"type": "string"
},
"submittedAt": {
"format": "date-time",
"type": "string"
}
},
"type": "object"
},
"ApplyAccountActionRequest": {
"additionalProperties": false,
"description": "Body for `POST /api/v1/account/actions` (the EPIC 48 moderation decision). The\r\noperator id is NOT accepted here — it is stamped server-side from the authenticated\r\nprincipal for un-spoofable due-process attribution.",
"properties": {
"action": {
"description": "Wire token of the graduated action (`warn`…`reinstate`…`dismiss`).",
"nullable": true,
"type": "string"
},
"duration": {
"description": "Optional human/token duration for a time-boxed action.",
"nullable": true,
"type": "string"
},
"policyClause": {
"description": "Policy / ToS clause the action is anchored to (mandatory).",
"nullable": true,
"type": "string"
},
"reasonCategory": {
"description": "Category-level reason disclosed to the user (mandatory).",
"nullable": true,
"type": "string"
},
"reasonInternalRef": {
"description": "Opaque pointer to the operator's internal notes; never the note text.",
"nullable": true,
"type": "string"
},
"reportId": {
"description": "Originating abuse-report id, when the action came from a triaged report.",
"format": "uuid",
"nullable": true,
"type": "string"
},
"scope": {
"description": "Scope token (`account` or a capability); defaults to `account`.",
"nullable": true,
"type": "string"
},
"targetUserId": {
"description": "The end-user account the action targets.",
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"ApplyAccountActionResult": {
"additionalProperties": false,
"properties": {
"actionId": {
"format": "uuid",
"type": "string"
},
"appealable": {
"type": "boolean"
},
"status": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"AssignAdviserToCaseRequest": {
"additionalProperties": false,
"description": "Request body for assigning an adviser to a client's case.",
"properties": {
"adviserUserId": {
"description": "The adviser taking the case.",
"format": "uuid",
"type": "string"
},
"caseReference": {
"description": "The agency's own opaque case reference.",
"nullable": true,
"type": "string"
},
"clientUserId": {
"description": "The client whose case it is.",
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"AssistActionDto": {
"additionalProperties": false,
"properties": {
"actionId": {
"format": "uuid",
"type": "string"
},
"actionType": {
"nullable": true,
"type": "string"
},
"assistantUserId": {
"format": "uuid",
"type": "string"
},
"occurredAt": {
"format": "date-time",
"type": "string"
},
"sessionId": {
"format": "uuid",
"type": "string"
},
"targetRef": {
"nullable": true,
"type": "string"
},
"touchedKeyMaterial": {
"type": "boolean"
}
},
"type": "object"
},
"AssistedRecoveryRequestBody": {
"additionalProperties": false,
"description": "Request body for a delegated assisted-recovery request.",
"properties": {
"context": {
"description": "Optional non-PII free-text hint to help the helpdesk verify the subject.",
"nullable": true,
"type": "string"
},
"reason": {
"description": "Why self-service is impossible — `lost-mfa` | `locked`. Optional: omitted or blank\r\ndefaults to `locked`. Any OTHER value is refused `400` rather than defaulted, because\r\na reason the subject stated and a reason they did not state are different facts and the\r\nhelpdesk agent reading the case cannot tell them apart afterwards (#8916).",
"nullable": true,
"type": "string"
},
"workEmail": {
"description": "The subject's work email — routing key into their org helpdesk queue.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"AssistedRecoveryRequestResponse": {
"additionalProperties": false,
"description": "Response for an accepted assisted-recovery request.",
"properties": {
"requestRef": {
"description": "The opaque request reference the subject can quote to their helpdesk.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"AssistedRecoveryStatusResponse": {
"additionalProperties": false,
"description": "Subject-facing status of a delegated assisted-recovery case (journey step 1b).\r\nMetadata only — see M:Essence.Identity.Auth.Api.Controllers.AssistedRecoveryController.GetStatus(System.Guid,System.Threading.CancellationToken).",
"properties": {
"canComplete": {
"description": "True when the subject may redeem their recovery token now.",
"type": "boolean"
},
"decidedAt": {
"description": "UTC instant the case was decided or completed; null while queued.",
"format": "date-time",
"nullable": true,
"type": "string"
},
"decisionReason": {
"description": "Machine reason slug when rejected; null otherwise.",
"nullable": true,
"type": "string"
},
"initiatedAt": {
"description": "UTC instant the request was raised.",
"format": "date-time",
"type": "string"
},
"reason": {
"description": "The subject's own stated reason (`lost-mfa` | `locked`).",
"nullable": true,
"type": "string"
},
"requestRef": {
"description": "Echo of the reference queried.",
"nullable": true,
"type": "string"
},
"status": {
"description": "`queued` | `authorised` | `rejected` | `completed` | `withdrawn`.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"AssurancePostureResult": {
"additionalProperties": false,
"properties": {
"attestedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"attestedBy": {
"nullable": true,
"type": "string"
},
"level": {
"nullable": true,
"type": "string"
},
"verified": {
"type": "boolean"
}
},
"type": "object"
},
"AssuranceRecordResult": {
"additionalProperties": false,
"properties": {
"auditAnchorReference": {
"nullable": true,
"type": "string"
},
"authority": {
"nullable": true,
"type": "string"
},
"canProceed": {
"type": "boolean"
},
"lastProvenance": {
"nullable": true,
"type": "string"
},
"level": {
"nullable": true,
"type": "string"
},
"levelRecordedAt": {
"format": "date-time",
"type": "string"
},
"proofingCompleted": {
"type": "boolean"
},
"proofingDisposition": {
"nullable": true,
"type": "string"
},
"proofingPolicy": {
"nullable": true,
"type": "string"
},
"recoveryDecisionRecordedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"recoveryDisposition": {
"nullable": true,
"type": "string"
},
"subjectUserId": {
"format": "uuid",
"type": "string"
},
"validUntil": {
"format": "date-time",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"AttestContactFieldRequest": {
"additionalProperties": false,
"description": "Request body for recording a contact-field provenance attestation.",
"properties": {
"assurance": {
"description": "`self_asserted | verified | attested`.",
"nullable": true,
"type": "string"
},
"fieldKey": {
"nullable": true,
"type": "string"
},
"signingKeyId": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"AttestProfessionalCredentialRequest": {
"additionalProperties": false,
"description": "Request body for recording a professional-credential attestation.",
"properties": {
"assurance": {
"description": "`self_asserted | verified | attested`.",
"nullable": true,
"type": "string"
},
"body": {
"nullable": true,
"type": "string"
},
"credentialType": {
"nullable": true,
"type": "string"
},
"expiresAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"fieldKey": {
"nullable": true,
"type": "string"
},
"signingKeyId": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"BackfillSetupPostureRequest": {
"additionalProperties": false,
"description": "Request body for the setup-posture backfill.",
"properties": {
"afterId": {
"description": "Keyset cursor — process accounts with an id strictly greater than this. Omit to start at the\r\nbeginning; pass back the previous call's `nextAfterId` to continue.",
"format": "uuid",
"nullable": true,
"type": "string"
},
"batchSize": {
"description": "Accounts per call. Clamped to Essence.Identity.Auth.Application.Commands.BackfillSetupPostureCommand.MaxBatchSize; a\r\nhard ceiling rather than a validation error, so a fat-fingered page size cannot move the\r\nwhole table in one request.",
"format": "int32",
"nullable": true,
"type": "integer"
},
"dryRun": {
"description": "When true, count the match set and publish nothing.",
"type": "boolean"
}
},
"type": "object"
},
"BackfillSetupPostureResult": {
"additionalProperties": false,
"properties": {
"announced": {
"format": "int32",
"type": "integer"
},
"complete": {
"readOnly": true,
"type": "boolean"
},
"custodial": {
"format": "int32",
"type": "integer"
},
"examined": {
"format": "int32",
"type": "integer"
},
"instantStamped": {
"format": "int32",
"type": "integer"
},
"nextAfterId": {
"format": "uuid",
"nullable": true,
"type": "string"
},
"totalAccounts": {
"format": "int32",
"type": "integer"
},
"verified": {
"format": "int32",
"type": "integer"
}
},
"type": "object"
},
"BeginWebAuthnAuthenticationRequest": {
"additionalProperties": false,
"properties": {
"userId": {
"format": "uuid",
"nullable": true,
"type": "string"
},
"userVerification": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"BeginWebAuthnRegistrationRequest": {
"additionalProperties": false,
"properties": {
"authenticatorAttachment": {
"nullable": true,
"type": "string"
},
"requireResidentKey": {
"description": "Nullable so the controller can distinguish \"caller didn't send this\"\r\n(→ defaults to TRUE, discoverable/passkey) from an explicit\r\n`false` opt-out. A plain `bool` here previously defaulted to\r\n`false` on every request that omitted the field — which was every\r\nFE call site — silently registering non-discoverable credentials that\r\nthe usernameless passkey login could never find.",
"nullable": true,
"type": "boolean"
},
"userVerification": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"BillingProfileDto": {
"additionalProperties": false,
"properties": {
"displayName": {
"nullable": true,
"type": "string"
},
"email": {
"nullable": true,
"type": "string"
},
"exists": {
"type": "boolean"
},
"userId": {
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"BiometricReenrolmentOversightResult": {
"additionalProperties": false,
"properties": {
"organizationId": {
"format": "uuid",
"type": "string"
},
"rows": {
"items": {
"$ref": "#/components/schemas/BiometricReenrolmentOversightRow"
},
"nullable": true,
"type": "array"
},
"stalledCount": {
"format": "int32",
"type": "integer"
},
"totalCount": {
"format": "int32",
"type": "integer"
}
},
"type": "object"
},
"BiometricReenrolmentOversightRow": {
"additionalProperties": false,
"properties": {
"currentStep": {
"nullable": true,
"type": "string"
},
"detectedAt": {
"format": "date-time",
"type": "string"
},
"elapsedMinutes": {
"format": "int32",
"type": "integer"
},
"memberRef": {
"nullable": true,
"type": "string"
},
"status": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"BiometricReenrolmentResult": {
"additionalProperties": false,
"properties": {
"assuranceRef": {
"nullable": true,
"type": "string"
},
"currentStep": {
"nullable": true,
"type": "string"
},
"detectedAt": {
"format": "date-time",
"type": "string"
},
"lockoutState": {
"nullable": true,
"type": "string"
},
"mismatchReason": {
"nullable": true,
"type": "string"
},
"reestablishAction": {
"nullable": true,
"type": "string"
},
"sessionId": {
"format": "uuid",
"type": "string"
},
"status": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"BlockDeviceRequest": {
"additionalProperties": false,
"properties": {
"reason": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"BlockDeviceResult": {
"additionalProperties": false,
"properties": {
"message": {
"nullable": true,
"type": "string"
},
"success": {
"type": "boolean"
}
},
"type": "object"
},
"BootstrapReturningNationalRequest": {
"additionalProperties": false,
"description": "Request body for a returning-national bootstrap. It carries no origin jurisdiction, scheme\r\nor foreign LoA: those are read from the caller's own intake (#14018), and any such field a\r\nclient still sends is ignored.",
"properties": {
"matchedPriorSovereignVaultRef": {
"nullable": true,
"type": "string"
},
"residualCheckSatisfied": {
"type": "boolean"
}
},
"type": "object"
},
"CancelPrimaryContactChangeResult": {
"additionalProperties": false,
"properties": {
"cancelledAt": {
"format": "date-time",
"type": "string"
},
"changeId": {
"format": "uuid",
"type": "string"
},
"status": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"CancelVerifiedNameChangeResult": {
"additionalProperties": false,
"properties": {
"cancelledAt": {
"format": "date-time",
"type": "string"
},
"changeId": {
"format": "uuid",
"type": "string"
},
"status": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"ChangeAdviceAgencyStandingRequest": {
"additionalProperties": false,
"description": "Request body for changing an agency's recognition standing.",
"properties": {
"action": {
"description": "One of `suspend`, `restore`, `withdraw`.",
"nullable": true,
"type": "string"
},
"reason": {
"description": "Required for `suspend` and `withdraw`.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"ChangePasswordRequest": {
"additionalProperties": false,
"description": "Request body for `POST /password/change`. Both fields are\r\nclient-derived PBKDF2 hashes — never plaintext passwords.",
"properties": {
"breachCheck": {
"description": "The client's breached-password check of the new password (DVS-4.7): `\"passed\"`,\r\n`\"not_performed\"`, or absent (recorded as `not_reported`). An honest-client fact.",
"nullable": true,
"type": "string"
},
"currentPasswordHash": {
"nullable": true,
"type": "string"
},
"newPasswordHash": {
"nullable": true,
"type": "string"
},
"passwordPolicyVersion": {
"description": "The client password-policy version (DVS-4.7); optional.",
"format": "int32",
"nullable": true,
"type": "integer"
}
},
"type": "object"
},
"ChangePasswordResult": {
"additionalProperties": false,
"properties": {
"errorMessage": {
"nullable": true,
"type": "string"
},
"sessionsRevoked": {
"format": "int32",
"type": "integer"
},
"success": {
"type": "boolean"
}
},
"type": "object"
},
"ChangeProfessionalAdviserStandingRequest": {
"additionalProperties": false,
"description": "Request body for changing an adviser's standing.",
"properties": {
"action": {
"description": "One of `suspend`, `reinstate`, `revoke`.",
"nullable": true,
"type": "string"
},
"reason": {
"description": "Required for `suspend` and `revoke`.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"ChangeSafeguardingAuthorityStandingRequest": {
"additionalProperties": false,
"description": "Request body for changing a body's recognition standing.",
"properties": {
"action": {
"description": "One of `suspend`, `restore`, `withdraw`.",
"nullable": true,
"type": "string"
},
"reason": {
"description": "Required for `suspend` and `withdraw`.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"ChangeSafeguardingOfficerStandingRequest": {
"additionalProperties": false,
"description": "Request body for changing an officer's standing.",
"properties": {
"action": {
"description": "One of `suspend`, `reinstate`, `revoke`.",
"nullable": true,
"type": "string"
},
"reason": {
"description": "Required for `suspend` and `revoke`.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"ClaimVaultContextDto": {
"additionalProperties": false,
"properties": {
"alreadyClaimed": {
"type": "boolean"
},
"requiredAssurance": {
"nullable": true,
"type": "string"
},
"status": {
"nullable": true,
"type": "string"
},
"subjectId": {
"format": "uuid",
"type": "string"
},
"whatChanges": {
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
},
"whatYouKeep": {
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
}
},
"type": "object"
},
"CoAuthoriserDirectoryEntry": {
"additionalProperties": false,
"properties": {
"authorisedSince": {
"format": "date-time",
"type": "string"
},
"authorityId": {
"format": "uuid",
"type": "string"
},
"authorityName": {
"nullable": true,
"type": "string"
},
"officerReference": {
"nullable": true,
"type": "string"
},
"officerUserId": {
"format": "uuid",
"type": "string"
},
"verificationLevel": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"CoAuthoriserDirectoryResult": {
"additionalProperties": false,
"properties": {
"officers": {
"items": {
"$ref": "#/components/schemas/CoAuthoriserDirectoryEntry"
},
"nullable": true,
"type": "array"
},
"totalCount": {
"format": "int32",
"type": "integer"
}
},
"type": "object"
},
"CommitAccountMergeRequest": {
"additionalProperties": false,
"description": "Wire body to commit a merge. The destructive confirm requires\r\nEssence.Identity.Auth.Api.Controllers.CommitAccountMergeRequest.AcknowledgeRetirement and a fresh survivor Essence.Identity.Auth.Api.Controllers.CommitAccountMergeRequest.StepUp\r\n(WCAG 2.2 SC 3.3.4, debt-2026-07-03-226); grant references stay optional.",
"properties": {
"acknowledgeRetirement": {
"description": "The survivor's affirmative acknowledgement that the folded account is retired.",
"type": "boolean"
},
"droppedGrantRefs": {
"description": "Grants not carried over — they end with the retired account (debt-2026-08-10-005).",
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
},
"policyDecision": {
"$ref": "#/components/schemas/MergePolicyDecisionInput"
},
"reconfirmRequiredGrantRefs": {
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
},
"repointedGrantRefs": {
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
},
"stepUp": {
"$ref": "#/components/schemas/MergeStepUpDto"
},
"suspendedGrantRefs": {
"description": "Regulated grants suspended pending re-confirmation (debt-2026-08-10-005).",
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
}
},
"type": "object"
},
"CommitAccountMergeResponse": {
"additionalProperties": false,
"properties": {
"auditRef": {
"description": "The EPIC 4 / 12 audit anchor reference for this merge (debt-2026-08-10-005) — the same\r\nvalue carried on `AccountMergedIntegrationEvent`, so the member's receipt and the\r\norganisation's projection quote one anchor for one merge.",
"nullable": true,
"type": "string"
},
"mergeSessionId": {
"format": "uuid",
"type": "string"
},
"mergedAt": {
"format": "date-time",
"type": "string"
},
"reversibleUntil": {
"format": "date-time",
"type": "string"
},
"status": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"CommitPrimaryContactChangeResult": {
"additionalProperties": false,
"properties": {
"changeId": {
"format": "uuid",
"type": "string"
},
"committedAt": {
"format": "date-time",
"type": "string"
},
"status": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"CommitVerifiedNameChangeRequest": {
"additionalProperties": false,
"description": "Wire body to commit the change (the EPIC 6 recipient split).",
"properties": {
"notifiedCount": {
"format": "int32",
"type": "integer"
},
"withheldCount": {
"format": "int32",
"type": "integer"
}
},
"type": "object"
},
"CommitVerifiedNameChangeResult": {
"additionalProperties": false,
"properties": {
"changeId": {
"format": "uuid",
"type": "string"
},
"committedAt": {
"format": "date-time",
"type": "string"
},
"notifiedCount": {
"format": "int32",
"type": "integer"
},
"status": {
"nullable": true,
"type": "string"
},
"withheldCount": {
"format": "int32",
"type": "integer"
}
},
"type": "object"
},
"CommunityVouchedAccount": {
"additionalProperties": false,
"properties": {
"auditAnchorReference": {
"nullable": true,
"type": "string"
},
"level": {
"nullable": true,
"type": "string"
},
"levelRecordedAt": {
"format": "date-time",
"type": "string"
},
"posture": {
"$ref": "#/components/schemas/CommunityVouchedPosture"
},
"provenance": {
"nullable": true,
"type": "string"
},
"subjectUserId": {
"format": "uuid",
"type": "string"
},
"validUntil": {
"format": "date-time",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"CommunityVouchedAccountsResult": {
"additionalProperties": false,
"properties": {
"accounts": {
"items": {
"$ref": "#/components/schemas/CommunityVouchedAccount"
},
"nullable": true,
"type": "array"
},
"expiringWithinDays": {
"format": "int32",
"type": "integer"
},
"truncated": {
"type": "boolean"
}
},
"type": "object"
},
"CommunityVouchedPosture": {
"enum": [
0,
1,
2
],
"format": "int32",
"type": "integer"
},
"CompleteAssistedRecoveryBody": {
"additionalProperties": false,
"description": "Request body for completing a delegated assisted recovery (journey step 4).",
"properties": {
"newPasswordHash": {
"description": "The client-derived hash of the subject's new credential. Plaintext\r\ncredentials never reach this service (zero-knowledge).",
"nullable": true,
"type": "string"
},
"recoveryToken": {
"description": "The opaque, single-use CC-061 authorise-only recovery-token reference the subject\r\nholds. A lookup handle bound to them — never key material.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"CompleteAssistedRecoveryResponse": {
"additionalProperties": false,
"description": "Response for a completed assisted recovery.",
"properties": {
"completed": {
"description": "True when the credential was set and the case closed.",
"type": "boolean"
},
"mfaReenrolmentRequired": {
"description": "True when a lost second factor was cleared and the subject must re-enrol MFA after\r\nsigning in.",
"type": "boolean"
}
},
"type": "object"
},
"CompleteMfaLoginCommand": {
"additionalProperties": false,
"properties": {
"challengeToken": {
"nullable": true,
"type": "string"
},
"code": {
"nullable": true,
"type": "string"
},
"ipAddress": {
"nullable": true,
"type": "string"
},
"method": {
"$ref": "#/components/schemas/MfaMethod"
},
"rememberDevice": {
"nullable": true,
"type": "boolean"
},
"userAgent": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"CompleteProofingRequest": {
"additionalProperties": false,
"description": "Body for recording a subject-reported proofing outcome.",
"properties": {
"failureReason": {
"description": "Short, non-PII failure reason when Essence.Identity.Auth.Api.Controllers.CompleteProofingRequest.Succeeded is false.",
"nullable": true,
"type": "string"
},
"succeeded": {
"description": "Defaults to `false` (fail closed). Sending `true` on the\r\nsubject endpoint is refused with 403 — a success must be adjudicated by\r\nthe proofing provider, not asserted by the subject.",
"type": "boolean"
}
},
"type": "object"
},
"CompleteWebAuthnAuthenticationRequest": {
"additionalProperties": false,
"properties": {
"authenticatorData": {
"nullable": true,
"type": "string"
},
"clientDataJson": {
"nullable": true,
"type": "string"
},
"credentialId": {
"nullable": true,
"type": "string"
},
"deviceFingerprint": {
"description": "The browser's device fingerprint, as its password sign-in sends it (#17966).",
"nullable": true,
"type": "string"
},
"deviceType": {
"description": "A `DeviceType` name; used only when the fingerprint registers a new device.",
"nullable": true,
"type": "string"
},
"sessionId": {
"nullable": true,
"type": "string"
},
"signature": {
"nullable": true,
"type": "string"
},
"userHandle": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"CompleteWebAuthnRegistrationRequest": {
"additionalProperties": false,
"properties": {
"attestationObject": {
"nullable": true,
"type": "string"
},
"clientDataJson": {
"nullable": true,
"type": "string"
},
"deviceName": {
"nullable": true,
"type": "string"
},
"sessionId": {
"nullable": true,
"type": "string"
},
"transports": {
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
}
},
"type": "object"
},
"ConfirmPhoneVerificationRequest": {
"additionalProperties": false,
"description": "Body of `POST /api/v1/auth/phone/verification/confirm`.",
"properties": {
"code": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"ConsentToAssistRequest": {
"additionalProperties": false,
"description": "Wire body for recording consent-to-assist.",
"properties": {
"assistantUserId": {
"format": "uuid",
"type": "string"
},
"assistedUserId": {
"description": "The assisted owner. Must be the authenticated caller when supplied (a mismatch is rejected\r\nwith 403); omit it and the caller is used. Retained so an existing client that sends its own\r\nid keeps working — it is no longer a way to name somebody else.",
"format": "uuid",
"nullable": true,
"type": "string"
},
"authorityBasis": {
"nullable": true,
"type": "string"
},
"expiresAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"scope": {
"nullable": true,
"type": "string"
},
"sessionId": {
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"ConsentToAssistResponse": {
"additionalProperties": false,
"description": "Response body for the consent call.",
"properties": {
"alreadyExisted": {
"type": "boolean"
},
"grantId": {
"format": "uuid",
"type": "string"
},
"sessionId": {
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"ContactFieldAttestationDto": {
"additionalProperties": false,
"properties": {
"assurance": {
"nullable": true,
"type": "string"
},
"fieldKey": {
"nullable": true,
"type": "string"
},
"signingKeyId": {
"nullable": true,
"type": "string"
},
"status": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"ContinueAfterDeviceLimitCommand": {
"additionalProperties": false,
"properties": {
"challengeToken": {
"nullable": true,
"type": "string"
},
"ipAddress": {
"nullable": true,
"type": "string"
},
"signOutDeviceIds": {
"items": {
"format": "uuid",
"type": "string"
},
"nullable": true,
"type": "array"
},
"userAgent": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"CreateTestTenantRequest": {
"additionalProperties": false,
"description": "Request body for M:Essence.Identity.Auth.Api.Controllers.TestTenantsController.CreateTestTenant(Essence.Identity.Auth.Api.Controllers.CreateTestTenantRequest).",
"properties": {
"email": {
"nullable": true,
"type": "string"
},
"homeRegion": {
"nullable": true,
"type": "string"
},
"passwordHash": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"CreateTestTenantResult": {
"additionalProperties": false,
"properties": {
"userId": {
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"CustodialEvidenceResult": {
"additionalProperties": false,
"properties": {
"code": {
"nullable": true,
"type": "string"
},
"label": {
"nullable": true,
"type": "string"
},
"note": {
"nullable": true,
"type": "string"
},
"required": {
"type": "boolean"
}
},
"type": "object"
},
"CustodialInstrumentResult": {
"additionalProperties": false,
"properties": {
"code": {
"nullable": true,
"type": "string"
},
"label": {
"nullable": true,
"type": "string"
},
"note": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"CustodialOrderResult": {
"additionalProperties": false,
"properties": {
"decidedAtIso": {
"nullable": true,
"type": "string"
},
"decisionAuthorityReference": {
"nullable": true,
"type": "string"
},
"decisionProvenance": {
"nullable": true,
"type": "string"
},
"grantedRights": {
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
},
"identityProvisioned": {
"type": "boolean"
},
"instrumentCode": {
"nullable": true,
"type": "string"
},
"instrumentLabel": {
"nullable": true,
"type": "string"
},
"jurisdictionCode": {
"nullable": true,
"type": "string"
},
"orderProofId": {
"nullable": true,
"type": "string"
},
"remediation": {
"nullable": true,
"type": "string"
},
"status": {
"nullable": true,
"type": "string"
},
"submittedAtIso": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"CustodialPolicyResult": {
"additionalProperties": false,
"properties": {
"acceptedInstruments": {
"items": {
"$ref": "#/components/schemas/CustodialInstrumentResult"
},
"nullable": true,
"type": "array"
},
"authoriserRole": {
"nullable": true,
"type": "string"
},
"jurisdiction": {
"nullable": true,
"type": "string"
},
"jurisdictionLabel": {
"nullable": true,
"type": "string"
},
"minimumAssurance": {
"nullable": true,
"type": "string"
},
"requiredEvidence": {
"items": {
"$ref": "#/components/schemas/CustodialEvidenceResult"
},
"nullable": true,
"type": "array"
},
"source": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"DeactivateUserResult": {
"additionalProperties": false,
"properties": {
"cancelBy": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"message": {
"nullable": true,
"type": "string"
},
"shredNotBefore": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"success": {
"type": "boolean"
}
},
"type": "object"
},
"DecideCustodialOrderRequest": {
"additionalProperties": false,
"description": "The named authoriser's decision on a pending order.",
"properties": {
"decidedByRef": {
"description": "The external authority's own reference for its decision (their case or order reference).",
"nullable": true,
"type": "string"
},
"remediation": {
"description": "Required on refusal: what the custodian must do next.",
"nullable": true,
"type": "string"
},
"verified": {
"type": "boolean"
}
},
"type": "object"
},
"DecideFraudClosureRequest": {
"additionalProperties": false,
"description": "Body of `POST account-closure-decisions/fraud`. The decider is the caller, never a body field.",
"properties": {
"accountId": {
"description": "The account to close.",
"format": "uuid",
"type": "string"
},
"evidenceReference": {
"description": "The fraud case reference — never the evidence.",
"nullable": true,
"type": "string"
},
"reasonCategory": {
"description": "`fraudulent-creation`, `synthetic-identity` or `terms-breach-unresolved-after-appeal`.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"DeclareOperatingJurisdictionRequest": {
"additionalProperties": false,
"description": "Body of `PUT /api/v1/sessions/current/operating-jurisdiction`.",
"properties": {
"jurisdiction": {
"description": "ISO 3166-1 alpha-2 code of the jurisdiction the caller is working from.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"DeclineInvitationCommand": {
"additionalProperties": false,
"properties": {
"token": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"DeclineInvitationResult": {
"additionalProperties": false,
"properties": {
"declined": {
"type": "boolean"
},
"invitationId": {
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"DeclineSupportAccessRequestBody": {
"additionalProperties": false,
"description": "Request body for declining a held support-access request (#21869).",
"properties": {
"reasonCode": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"DelegateAccessGrantCreatedResponse": {
"additionalProperties": false,
"description": "Response body for the grant call.",
"properties": {
"alreadyExisted": {
"type": "boolean"
},
"grantId": {
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"DelegateAccessGrantDto": {
"additionalProperties": false,
"properties": {
"authorityBasis": {
"nullable": true,
"type": "string"
},
"capabilities": {
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
},
"delegateUserId": {
"format": "uuid",
"type": "string"
},
"delegationId": {
"format": "uuid",
"type": "string"
},
"expiresAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"grantId": {
"format": "uuid",
"type": "string"
},
"principalUserId": {
"format": "uuid",
"type": "string"
},
"revokedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"status": {
"$ref": "#/components/schemas/DelegateAccessStatus"
},
"surface": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"DelegateAccessStatus": {
"enum": [
0,
1,
2
],
"format": "int32",
"type": "integer"
},
"DelegatedAgentDto": {
"additionalProperties": false,
"properties": {
"agentId": {
"format": "uuid",
"type": "string"
},
"agentReference": {
"nullable": true,
"type": "string"
},
"createdAt": {
"format": "date-time",
"type": "string"
},
"grantedScopes": {
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
},
"name": {
"nullable": true,
"type": "string"
},
"organisationId": {
"format": "uuid",
"nullable": true,
"type": "string"
},
"publicKeyJwk": {
"nullable": true,
"type": "string"
},
"publicKeyRegisteredAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"publicKeyThumbprint": {
"nullable": true,
"type": "string"
},
"status": {
"$ref": "#/components/schemas/DelegatedAgentStatus"
},
"suspendedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"suspendedForIncidentId": {
"format": "uuid",
"nullable": true,
"type": "string"
},
"suspensionReason": {
"nullable": true,
"type": "string"
},
"suspensionReference": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"DelegatedAgentStatus": {
"enum": [
0,
1,
2
],
"format": "int32",
"type": "integer"
},
"DeleteDeviceResult": {
"additionalProperties": false,
"properties": {
"message": {
"nullable": true,
"type": "string"
},
"sessionsRevoked": {
"format": "int32",
"type": "integer"
},
"success": {
"type": "boolean"
}
},
"type": "object"
},
"DesignateSafeguardingOfficerRequest": {
"additionalProperties": false,
"description": "Request body for designating an officer.",
"properties": {
"officerReference": {
"description": "Optional opaque, authority-chosen, non-PII reference (a warrant or staff number).",
"nullable": true,
"type": "string"
},
"officerUserId": {
"description": "The officer's user-principal id.",
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"DetectedAccountResult": {
"additionalProperties": false,
"properties": {
"accountId": {
"format": "uuid",
"type": "string"
},
"detectedAt": {
"format": "date-time",
"type": "string"
},
"domain": {
"nullable": true,
"type": "string"
},
"domainProofId": {
"format": "uuid",
"type": "string"
},
"emailMasked": {
"nullable": true,
"type": "string"
},
"state": {
"nullable": true,
"type": "string"
},
"subjectId": {
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"DeviceDto": {
"additionalProperties": false,
"properties": {
"createdAt": {
"format": "date-time",
"type": "string"
},
"deviceType": {
"$ref": "#/components/schemas/DeviceType"
},
"fingerprint": {
"nullable": true,
"type": "string"
},
"friendlyName": {
"nullable": true,
"type": "string"
},
"id": {
"format": "uuid",
"type": "string"
},
"ipAddress": {
"nullable": true,
"type": "string"
},
"lastIpAddress": {
"nullable": true,
"type": "string"
},
"lastUsedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"trustLevel": {
"$ref": "#/components/schemas/DeviceTrustLevel"
},
"trustedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"updatedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"userAgent": {
"nullable": true,
"type": "string"
},
"userId": {
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"DeviceLimitPause": {
"additionalProperties": false,
"properties": {
"activeDevices": {
"items": {
"$ref": "#/components/schemas/ActiveDeviceSummary"
},
"nullable": true,
"type": "array"
},
"allowance": {
"format": "int64",
"type": "integer"
},
"challengeToken": {
"nullable": true,
"type": "string"
},
"expiresAt": {
"format": "date-time",
"type": "string"
},
"message": {
"nullable": true,
"type": "string"
},
"upgradeMessage": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"DeviceTrustLevel": {
"enum": [
0,
1,
2,
3
],
"format": "int32",
"type": "integer"
},
"DeviceType": {
"enum": [
0,
1,
2,
3,
4,
5
],
"format": "int32",
"type": "integer"
},
"DisableMfaCommand": {
"additionalProperties": false,
"properties": {
"currentPassword": {
"nullable": true,
"type": "string"
},
"userId": {
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"DisableMfaResult": {
"additionalProperties": false,
"properties": {
"message": {
"nullable": true,
"type": "string"
},
"success": {
"type": "boolean"
}
},
"type": "object"
},
"DiscoverRealmRequest": {
"additionalProperties": false,
"description": "Request for `POST /discover`. Supply exactly one identifier: `host` for an org-branded\r\nsign-in URL, or `email`/`emailHash` for a general user. `host` takes precedence.\r\nAll fields are optional — a request with none is answered with the region-default realm, the same\r\nas any unresolved identifier, so an empty probe is not distinguishable either.",
"properties": {
"domain": {
"description": "The sign-in address's email DOMAIN, for clients that prefer not to send the address at all.\r\nWins over the domain derived from Essence.Identity.Auth.Api.Controllers.DiscoverRealmRequest.Email.",
"nullable": true,
"type": "string"
},
"email": {
"description": "General user's sign-in address. Only its DOMAIN is used to resolve a realm and only the\r\ndomain is forwarded to the registry; the address itself is never stored or forwarded, and\r\nits hash is used only as the internal audit trail's subject reference (#8633).",
"nullable": true,
"type": "string"
},
"emailHash": {
"description": "Pre-computed SHA-256 hex of the lower-cased address. Retained as the audit subject reference\r\nfor clients that send neither the address nor the domain; it resolves no realm, because a\r\nkey the caller chooses and the answer varies with is an account-existence oracle (#8633).",
"nullable": true,
"type": "string"
},
"host": {
"description": "Org-branded sign-in host, e.g. `acme.gb.onessence.digital`.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"DiscoverRealmResponse": {
"additionalProperties": false,
"description": "Response for `POST /discover` — where to broker the sign-in. Deliberately carries no\r\n\"resolved\" flag: whether the identifier was known is exactly what NFR-09.020 forbids disclosing.",
"properties": {
"authorizeUrl": {
"description": "The completing instance's OIDC authorize endpoint to redirect to.",
"nullable": true,
"type": "string"
},
"realmToken": {
"description": "Registry-signed, short-TTL realm-redirect descriptor. Opaque to the client.",
"nullable": true,
"type": "string"
},
"region": {
"description": "ISO-3166 alpha-2 region of the completing instance.",
"nullable": true,
"type": "string"
},
"state": {
"description": "Opaque continuation value to carry through the redirect as the OIDC `state`.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"DomainDetectionResult": {
"additionalProperties": false,
"properties": {
"accounts": {
"items": {
"$ref": "#/components/schemas/DetectedAccountResult"
},
"nullable": true,
"type": "array"
},
"completedAt": {
"format": "date-time",
"type": "string"
},
"domain": {
"nullable": true,
"type": "string"
},
"domainProofId": {
"format": "uuid",
"type": "string"
},
"runId": {
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"DormancyInfo": {
"additionalProperties": false,
"properties": {
"effectiveThresholdMonths": {
"format": "int32",
"nullable": true,
"type": "integer"
},
"isDormantReactivation": {
"type": "boolean"
},
"lastActiveLabel": {
"nullable": true,
"type": "string"
},
"monthsInactive": {
"format": "int32",
"type": "integer"
},
"thresholdSource": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"EmergencyFreezeRequest": {
"additionalProperties": false,
"description": "Request body for the emergency freeze. `reason` is an optional non-PII token.",
"properties": {
"reason": {
"description": "Why the freeze is being placed (e.g. `suspected-account-takeover`).",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"EmergencyFreezeResponse": {
"additionalProperties": false,
"description": "Response for a successful emergency freeze.",
"properties": {
"frozenAt": {
"description": "UTC instant the freeze is in force from.",
"format": "date-time",
"type": "string"
},
"incidentId": {
"description": "The takeover incident the freeze opened or joined (#7393).",
"format": "uuid",
"type": "string"
},
"sessionsTerminated": {
"description": "Number of active sessions terminated by the freeze.",
"format": "int32",
"type": "integer"
}
},
"type": "object"
},
"EnableMfaWithTotpResult": {
"additionalProperties": false,
"properties": {
"backupCodes": {
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
},
"qrCodeBase64": {
"nullable": true,
"type": "string"
},
"qrCodeUri": {
"nullable": true,
"type": "string"
},
"success": {
"type": "boolean"
},
"totpSecret": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"EndAdviserCaseAssignmentRequest": {
"additionalProperties": false,
"description": "Request body for closing a case.",
"properties": {
"reason": {
"description": "Why the case is closing.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"EnrolAlternateCredentialRequest": {
"additionalProperties": false,
"description": "Body of `PUT /api/v1/users/me/protection-status/alternate-credential`. Carries the\r\nclient-derived hash of the alternate passphrase and nothing else — zero-knowledge: the\r\npassphrase itself never reaches the server.",
"properties": {
"passwordHash": {
"description": "Client-derived hash of the alternate passphrase (same derivation as sign-in).",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"EnrolRecoveryPhraseRequest": {
"additionalProperties": false,
"description": "Request body for `POST /recovery-phrase/enrol`. Essence.Identity.Auth.Api.Controllers.EnrolRecoveryPhraseRequest.RecoveryProof is the\r\nclient-derived recovery proof (hex, ≥ 64 chars) — never the 24-word phrase or the seed.",
"properties": {
"recoveryProof": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"EnrolSharedDeviceRequest": {
"additionalProperties": false,
"description": "Enrolment body. Carries no organisation — that comes from the route.",
"properties": {
"label": {
"description": "The administrator's name for the machine.",
"nullable": true,
"type": "string"
},
"publicKeyJwk": {
"description": "The machine's EC P-256 public JWK, as a JSON string.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"EnrolSupportAgentRequestBody": {
"additionalProperties": false,
"description": "Request body for enrolling a support agent.",
"properties": {
"appId": {
"format": "uuid",
"type": "string"
},
"displayName": {
"nullable": true,
"type": "string"
},
"email": {
"nullable": true,
"type": "string"
},
"role": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"EstablishActingAsSessionRequest": {
"additionalProperties": false,
"description": "Request body for establishing an acting-as session.",
"properties": {
"grantId": {
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"EstablishActingAsSessionResult": {
"additionalProperties": false,
"properties": {
"actingAsToken": {
"nullable": true,
"type": "string"
},
"capabilities": {
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
},
"delegationId": {
"format": "uuid",
"type": "string"
},
"expiresAt": {
"format": "date-time",
"type": "string"
},
"grantId": {
"format": "uuid",
"type": "string"
},
"principalUserId": {
"format": "uuid",
"type": "string"
},
"surface": {
"nullable": true,
"type": "string"
},
"tokenId": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"EstablishGuardianshipRequest": {
"additionalProperties": false,
"description": "Request body for establishing a guardianship (Step 1 seam).",
"properties": {
"childDisplayName": {
"description": "The guardian-supplied ward display label.",
"nullable": true,
"type": "string"
},
"childId": {
"description": "Optional pre-existing minor platform id; when absent a fresh id is minted.",
"format": "uuid",
"nullable": true,
"type": "string"
},
"guardians": {
"description": "The named guardian links. Must contain exactly one primary.",
"items": {
"$ref": "#/components/schemas/GuardianLinkDto"
},
"nullable": true,
"type": "array"
}
},
"type": "object"
},
"ExecutorOfficerAttestationResult": {
"additionalProperties": false,
"properties": {
"attested": {
"type": "boolean"
},
"officerUserId": {
"format": "uuid",
"type": "string"
},
"organizationId": {
"format": "uuid",
"type": "string"
},
"verifiedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"ExecutorOfficerRow": {
"additionalProperties": false,
"properties": {
"attested": {
"type": "boolean"
},
"officerReference": {
"nullable": true,
"type": "string"
},
"officerUserId": {
"format": "uuid",
"type": "string"
},
"removalReason": {
"nullable": true,
"type": "string"
},
"removedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"rosteredAt": {
"format": "date-time",
"type": "string"
},
"status": {
"nullable": true,
"type": "string"
},
"verificationLevel": {
"nullable": true,
"type": "string"
},
"verifiedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"ExecutorRosterResult": {
"additionalProperties": false,
"properties": {
"officers": {
"items": {
"$ref": "#/components/schemas/ExecutorOfficerRow"
},
"nullable": true,
"type": "array"
},
"organizationId": {
"format": "uuid",
"type": "string"
},
"totalCount": {
"format": "int32",
"type": "integer"
},
"verifiedCount": {
"format": "int32",
"type": "integer"
}
},
"type": "object"
},
"ExpiringVerificationRow": {
"additionalProperties": false,
"properties": {
"checkType": {
"nullable": true,
"type": "string"
},
"daysToExpiry": {
"format": "int32",
"type": "integer"
},
"lastReminderSentAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"recheckRequestedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"status": {
"nullable": true,
"type": "string"
},
"subjectReference": {
"nullable": true,
"type": "string"
},
"validFrom": {
"format": "date-time",
"type": "string"
},
"validUntil": {
"format": "date-time",
"type": "string"
},
"verificationId": {
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"ExpiringVerificationsCohortResult": {
"additionalProperties": false,
"properties": {
"expiredCount": {
"format": "int32",
"type": "integer"
},
"organizationId": {
"format": "uuid",
"type": "string"
},
"recheckRequestedCount": {
"format": "int32",
"type": "integer"
},
"rows": {
"items": {
"$ref": "#/components/schemas/ExpiringVerificationRow"
},
"nullable": true,
"type": "array"
},
"totalCount": {
"format": "int32",
"type": "integer"
},
"windowDays": {
"format": "int32",
"type": "integer"
}
},
"type": "object"
},
"ExtendProofChallengeRequest": {
"additionalProperties": false,
"description": "Extension request.",
"properties": {
"byDays": {
"description": "How many more days to allow. Bounded by the aggregate.",
"format": "double",
"type": "number"
}
},
"type": "object"
},
"FieldAttestationResult": {
"additionalProperties": false,
"properties": {
"assurance": {
"nullable": true,
"type": "string"
},
"attestationId": {
"format": "uuid",
"type": "string"
},
"fieldKey": {
"nullable": true,
"type": "string"
},
"status": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"FreezeBySignedLinkRequest": {
"additionalProperties": false,
"description": "Request body for the signed-link emergency freeze — the four fields carried by an\r\nFR-66.114 freeze deep link (`?account=&session=&exp=&sig=`).",
"properties": {
"accountId": {
"description": "Account the link authorises a freeze on.",
"format": "uuid",
"type": "string"
},
"expiresAtUnix": {
"description": "Link expiry, seconds since the Unix epoch.",
"format": "int64",
"type": "integer"
},
"recoverySessionId": {
"description": "The in-flight recovery attempt the link names.",
"nullable": true,
"type": "string"
},
"signature": {
"description": "Lower-case hex HMAC-SHA256 digest minted by EPIC 66.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"FreezeBySignedLinkResponse": {
"additionalProperties": false,
"description": "Response for a signed-link freeze. Every field exists so the landing page can state what\r\nit actually stopped rather than a generic success — the reader is deciding whether they\r\nstill need to ring support tonight.",
"properties": {
"alreadyFrozen": {
"description": "Whether the freeze was already in force before this call.",
"type": "boolean"
},
"frozenAt": {
"description": "UTC instant the freeze is in force from.",
"format": "date-time",
"nullable": true,
"type": "string"
},
"recoveryDiscarded": {
"description": "Whether an in-flight recovery attempt was actually discarded. False when the named\r\nattempt had already finished, or is owned by a bounded context Auth cannot halt — never\r\nrounded up.",
"type": "boolean"
},
"sessionsTerminated": {
"description": "Active sessions terminated by the freeze.",
"format": "int32",
"type": "integer"
}
},
"type": "object"
},
"GrantApprovalDecisionRequest": {
"additionalProperties": false,
"description": "Request body for an owner's decision, matching the org-portal's\r\n`GrantApprovalDecision`. Deliberately carries NO approver identity — that is\r\nresolved from the caller's JWT.",
"properties": {
"decision": {
"nullable": true,
"type": "string"
},
"reason": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"GrantDelegateAccessRequest": {
"additionalProperties": false,
"description": "Wire body for granting delegate access.",
"properties": {
"authorityBasis": {
"nullable": true,
"type": "string"
},
"capabilities": {
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
},
"delegateUserId": {
"format": "uuid",
"type": "string"
},
"delegationId": {
"format": "uuid",
"type": "string"
},
"expiresAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"partnerAppId": {
"description": "Partner support impersonation only (`authorityBasis=support-impersonation`): the\r\nEPIC 25 partner application the acting agent belongs to. Required for that basis so the\r\ndual-identity audit can name the partner, not only the person.",
"format": "uuid",
"nullable": true,
"type": "string"
},
"principalUserId": {
"description": "Optional explicit principal. Defaults to the caller; any other value is refused (403).",
"format": "uuid",
"nullable": true,
"type": "string"
},
"reasonCode": {
"description": "Partner support impersonation only: the governed reason code from the partner's\r\nconfigured set (an operational token, never free prose).",
"nullable": true,
"type": "string"
},
"surface": {
"nullable": true,
"type": "string"
},
"ticketReference": {
"description": "Partner support impersonation only: the partner's own ticket reference, exactly as shown\r\nto the subject on the consent screen.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"GrantProbateRoleRequest": {
"additionalProperties": false,
"description": "Wire body for the EPIC 15 → EPIC 9 probate-role grant call.",
"properties": {
"attorneyUserId": {
"format": "uuid",
"type": "string"
},
"estateId": {
"format": "uuid",
"nullable": true,
"type": "string"
},
"expiresAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"grantedByUserId": {
"description": "Optional explicit supervising-partner attribution (org-portal direct grants).",
"format": "uuid",
"nullable": true,
"type": "string"
},
"grantorUserId": {
"format": "uuid",
"nullable": true,
"type": "string"
},
"jurisdiction": {
"nullable": true,
"type": "string"
},
"poaId": {
"format": "uuid",
"nullable": true,
"type": "string"
},
"poaType": {
"nullable": true,
"type": "string"
},
"scope": {
"$ref": "#/components/schemas/ProbateRoleScopeRequest"
}
},
"type": "object"
},
"GuardianLinkDto": {
"additionalProperties": false,
"properties": {
"guardianId": {
"format": "uuid",
"type": "string"
},
"isPrimary": {
"type": "boolean"
},
"relationship": {
"nullable": true,
"type": "string"
},
"role": {
"nullable": true,
"type": "string"
},
"scope": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"GuardianRosterDto": {
"additionalProperties": false,
"properties": {
"childDisplayName": {
"nullable": true,
"type": "string"
},
"childId": {
"nullable": true,
"type": "string"
},
"guardians": {
"items": {
"$ref": "#/components/schemas/GuardianSeatDto"
},
"nullable": true,
"type": "array"
},
"guardianshipId": {
"nullable": true,
"type": "string"
},
"status": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"GuardianSeatDto": {
"additionalProperties": false,
"properties": {
"activatedAtIso": {
"nullable": true,
"type": "string"
},
"guardianId": {
"nullable": true,
"type": "string"
},
"isActive": {
"type": "boolean"
},
"isPrimary": {
"type": "boolean"
},
"relationship": {
"nullable": true,
"type": "string"
},
"role": {
"nullable": true,
"type": "string"
},
"scope": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"GuardianshipCorroborationResult": {
"additionalProperties": false,
"properties": {
"corroborated": {
"type": "boolean"
},
"guardianId": {
"format": "uuid",
"type": "string"
},
"guardianshipId": {
"format": "uuid",
"nullable": true,
"type": "string"
},
"minorSubjectId": {
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"GuardianshipResultDto": {
"additionalProperties": false,
"properties": {
"childId": {
"nullable": true,
"type": "string"
},
"guardianshipId": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"HandoverConfirmationDto": {
"additionalProperties": false,
"properties": {
"guardianAccessEnded": {
"type": "boolean"
},
"revocationDateIso": {
"nullable": true,
"type": "string"
},
"revokedGuardianIds": {
"items": {
"format": "uuid",
"type": "string"
},
"nullable": true,
"type": "array"
},
"status": {
"nullable": true,
"type": "string"
},
"subjectId": {
"format": "uuid",
"type": "string"
},
"whoHasAccess": {
"items": {
"format": "uuid",
"type": "string"
},
"nullable": true,
"type": "array"
}
},
"type": "object"
},
"IdentityAttestation": {
"additionalProperties": false,
"properties": {
"attestedAt": {
"format": "date-time",
"type": "string"
},
"auditAnchorReference": {
"nullable": true,
"type": "string"
},
"evidenceKinds": {
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
},
"level": {
"nullable": true,
"type": "string"
},
"verifier": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"IdentityAttestedReprovisionRequest": {
"additionalProperties": false,
"properties": {
"newPasswordHash": {
"nullable": true,
"type": "string"
},
"proofingSessionId": {
"format": "uuid",
"type": "string"
},
"requestVaultReprovision": {
"type": "boolean"
},
"subjectUserId": {
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"IdentityAttestedReprovisionResult": {
"additionalProperties": false,
"properties": {
"attestation": {
"$ref": "#/components/schemas/IdentityAttestation"
},
"recoveryMaterialSurveyed": {
"nullable": true,
"type": "string"
},
"reprovisionId": {
"format": "uuid",
"type": "string"
},
"reprovisionedAt": {
"format": "date-time",
"type": "string"
},
"subjectUserId": {
"format": "uuid",
"type": "string"
},
"vaultReprovisionRequested": {
"type": "boolean"
}
},
"type": "object"
},
"IdentityChangeRecordDto": {
"additionalProperties": false,
"properties": {
"changedAtIso": {
"nullable": true,
"type": "string"
},
"from": {
"nullable": true,
"type": "string"
},
"guardianshipId": {
"format": "uuid",
"nullable": true,
"type": "string"
},
"identityChangeRef": {
"nullable": true,
"type": "string"
},
"subjectId": {
"format": "uuid",
"type": "string"
},
"to": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"IndividualRecoveryCancelBody": {
"additionalProperties": false,
"properties": {
"cancelToken": {
"description": "The token from the text message's link.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"IndividualRecoveryCancelResponse": {
"additionalProperties": false,
"properties": {
"cancelled": {
"type": "boolean"
}
},
"type": "object"
},
"IndividualRecoveryCompleteBody": {
"additionalProperties": false,
"properties": {
"completionToken": {
"description": "The token the proof step returned.",
"nullable": true,
"type": "string"
},
"newPasswordHash": {
"description": "The CLIENT-DERIVED verifier of the new password; never the password itself.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"IndividualRecoveryCompleteResponse": {
"additionalProperties": false,
"properties": {
"completed": {
"description": "True when the new credential is set.",
"type": "boolean"
},
"secondFactorReenrolmentRequired": {
"description": "Always true: every old factor was removed.",
"type": "boolean"
}
},
"type": "object"
},
"IndividualRecoveryProofBody": {
"additionalProperties": false,
"description": "The two codes: one from the email of record, one from the verified phone.",
"properties": {
"emailCode": {
"nullable": true,
"type": "string"
},
"smsCode": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"IndividualRecoveryProofResponse": {
"additionalProperties": false,
"properties": {
"completeBy": {
"description": "The latest it can be completed (UTC); after it, start again.",
"format": "date-time",
"type": "string"
},
"completionToken": {
"description": "Shown once. Keep it: it is the only way to finish this recovery.",
"nullable": true,
"type": "string"
},
"holdEndsAt": {
"description": "The earliest the recovery can be completed (UTC).",
"format": "date-time",
"type": "string"
}
},
"type": "object"
},
"InitiateOAuthLinkRequest": {
"additionalProperties": false,
"description": "Request model for starting a link flow (`{provider}/link/authorize`). Carries no user id:\r\nthe account to link is the signed-in caller, read from the bearer token.",
"properties": {
"redirectUri": {
"description": "Redirect URI where the OAuth provider will send the authorization code.\r\nMust match exactly with the URI registered with the provider.",
"nullable": true,
"type": "string"
},
"scopes": {
"description": "Optional scopes to request. If not provided, default scopes will be used.",
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
}
},
"type": "object"
},
"InitiateOAuthRequest": {
"additionalProperties": false,
"description": "Request model for initiating OAuth flow.",
"properties": {
"deviceFingerprint": {
"description": "Optional device fingerprint for device tracking.",
"nullable": true,
"type": "string"
},
"homeRegion": {
"description": "Optional sovereign home region chosen on the sign-up surface (ISO 3166-1 alpha-2,\r\ne.g. \"GB\"/\"DE\"/\"AE\"; FR-44.040, D-123). Stored in the OAuth state and applied when the\r\ncallback creates a NEW account, so the account and its default vault are provisioned in\r\nthe chosen region. \"GLOBAL\" and blank are not valid regions and fall back to the\r\nsovereign default (counted as an onboarding fault).",
"nullable": true,
"type": "string"
},
"redirectUri": {
"description": "Redirect URI where the OAuth provider will send the authorization code.\r\nMust match exactly with the URI registered with the provider.",
"nullable": true,
"type": "string"
},
"scopes": {
"description": "Optional scopes to request. If not provided, default scopes will be used.",
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
}
},
"type": "object"
},
"InitiateOAuthResult": {
"additionalProperties": false,
"properties": {
"authorizationUrl": {
"nullable": true,
"type": "string"
},
"codeVerifier": {
"nullable": true,
"type": "string"
},
"expiresAt": {
"format": "date-time",
"type": "string"
},
"state": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"InitiateProbateStepUpRequest": {
"additionalProperties": false,
"description": "Request body for initiating a probate step-up. `authorityBasis` and\r\n`factor` carry the contract's kebab-case wire values (`court-grant` |\r\n`probate-role`; `email` | `sms` | `webauthn` |\r\n`phone-call` | `postal-code`) — see\r\nEssence.Identity.Auth.Api.Controllers.SendProbateStepUpChallengeRequest for why they are strings.",
"properties": {
"authorityBasis": {
"nullable": true,
"type": "string"
},
"estateId": {
"format": "uuid",
"type": "string"
},
"factor": {
"nullable": true,
"type": "string"
},
"factorProof": {
"nullable": true,
"type": "string"
},
"grantDocumentId": {
"nullable": true,
"type": "string"
},
"grantReference": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"InitiateProofingRequest": {
"additionalProperties": false,
"description": "Body for initiating a proofing session (capability (c)).",
"properties": {
"provider": {
"description": "The proofing provider to route to (defaults to `self-serve`).",
"nullable": true,
"type": "string"
},
"relyingServiceId": {
"description": "The relying service / gated action this run is for (e.g. `loan-drawdown`) —\r\nthe key the governing org's assurance-threshold policy is resolved by\r\n(debt-2026-08-13-211).",
"nullable": true,
"type": "string"
},
"requiredLevel": {
"description": "The level the requesting action says it needs (`loa1`|`loa2`|`loa3`).\r\nAdvisory only: the org policy resolved server-side may raise it, and a\r\ncaller can never lower what its organisation demands.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"InitiateSafeRecoveryRequestBody": {
"additionalProperties": false,
"description": "Request body for initiating safe recovery.",
"properties": {
"reason": {
"description": "Optional short, non-PII reason.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"InitiateSafeRecoveryResult": {
"additionalProperties": false,
"properties": {
"claimId": {
"format": "uuid",
"type": "string"
},
"initiatedAtIso": {
"nullable": true,
"type": "string"
},
"status": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"InitiateStepUpRequest": {
"additionalProperties": false,
"description": "Request body for initiating a generic step-up. `action` and `factor`\r\ncarry the contract's kebab-case wire values (`recovery-initiate` |\r\n`password-change` | `verification-renewal`; `totp` | `sms` |\r\n`email` | `webauthn`).",
"properties": {
"action": {
"nullable": true,
"type": "string"
},
"factor": {
"nullable": true,
"type": "string"
},
"factorProof": {
"nullable": true,
"type": "string"
},
"passwordHash": {
"description": "The client-derived password hash, REQUIRED for actions that need password\r\nre-verification in addition to a second factor — today\r\n`account-closure` (FR-15.008.7, debt-2026-08-19-008).\r\n\n\r\nZero-knowledge: the same client-side hash the login and change-password\r\ncontracts carry. The plaintext password never reaches the server; the\r\ncomparison is constant-time in the domain.\r\n\nOmit for every action a second factor alone elevates.",
"nullable": true,
"type": "string"
},
"reactivationCorrelationId": {
"description": "Optional correlation id from the flow requesting the elevation (e.g. the\r\ndormant-account reactivation). Echoed onto the emitted\r\n`SessionElevatedIntegrationEvent` for cross-service audit correlation\r\n(debt-2026-07-08-107). Ignored for non-correlated actions.",
"nullable": true,
"type": "string"
},
"resourceBinding": {
"description": "Optional opaque reference to the single resource the elevation is for — e.g.\r\nthe contact card id being re-attested with\r\n`action=connection-trust-action` (debt-2026-08-13-009). Stamped onto the\r\ntoken's `rsc` claim so a consumer can refuse an elevation taken for a\r\ndifferent resource. Omit for account-wide elevations.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"InitiateStepUpResponse": {
"additionalProperties": false,
"description": "Wire form of Essence.Identity.Auth.Application.Commands.StepUp.InitiateStepUpResult (#10652).",
"properties": {
"assertion": {
"$ref": "#/components/schemas/StepUpAssertionResponse"
},
"expiresAt": {
"format": "date-time",
"type": "string"
},
"maxExpiresAt": {
"format": "date-time",
"type": "string"
},
"sessionId": {
"nullable": true,
"type": "string"
},
"stepUpToken": {
"nullable": true,
"type": "string"
},
"warnAt": {
"format": "date-time",
"type": "string"
}
},
"type": "object"
},
"InvitationDetailDto": {
"additionalProperties": false,
"properties": {
"department": {
"nullable": true,
"type": "string"
},
"email": {
"nullable": true,
"type": "string"
},
"emailMasked": {
"nullable": true,
"type": "string"
},
"expiresAt": {
"format": "date-time",
"type": "string"
},
"homeRegion": {
"nullable": true,
"type": "string"
},
"invitationId": {
"format": "uuid",
"type": "string"
},
"invitedByDisplayName": {
"nullable": true,
"type": "string"
},
"onboarding": {
"$ref": "#/components/schemas/InvitationOnboardingDto"
},
"organizationId": {
"format": "uuid",
"type": "string"
},
"organizationName": {
"nullable": true,
"type": "string"
},
"roles": {
"items": {
"$ref": "#/components/schemas/InvitationRoleDto"
},
"nullable": true,
"type": "array"
},
"sponsoredPremium": {
"$ref": "#/components/schemas/InvitationSponsoredPremiumDto"
},
"status": {
"nullable": true,
"type": "string"
},
"vaultScope": {
"$ref": "#/components/schemas/InvitationVaultScopeDto"
}
},
"type": "object"
},
"InvitationOnboardingDto": {
"additionalProperties": false,
"properties": {
"requiresMfa": {
"type": "boolean"
},
"requiresPhoneVerification": {
"type": "boolean"
},
"requiresRecovery": {
"type": "boolean"
}
},
"type": "object"
},
"InvitationRoleDto": {
"additionalProperties": false,
"properties": {
"description": {
"nullable": true,
"type": "string"
},
"name": {
"nullable": true,
"type": "string"
},
"roleId": {
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"InvitationSponsoredPremiumDto": {
"additionalProperties": false,
"properties": {
"entitlementLabel": {
"nullable": true,
"type": "string"
},
"planLabel": {
"nullable": true,
"type": "string"
},
"sponsorName": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"InvitationVaultScopeDto": {
"additionalProperties": false,
"properties": {
"access": {
"nullable": true,
"type": "string"
},
"description": {
"nullable": true,
"type": "string"
},
"vaultLabel": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"InviteOrganizationMemberRequest": {
"additionalProperties": false,
"description": "Request body for inviting an organisation member. Carries the invitee and nothing else: the\r\norganisation is in the route, the inviter is in the token, and no role may be pre-assigned.",
"properties": {
"inviteeEmail": {
"description": "The person being invited.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"InviteOrganizationMemberResult": {
"additionalProperties": false,
"properties": {
"expiresAt": {
"format": "date-time",
"type": "string"
},
"invitationId": {
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"IssueMajorityTransitionRekeyTokenResult": {
"additionalProperties": false,
"properties": {
"claimId": {
"format": "uuid",
"type": "string"
},
"expiresAtIso": {
"nullable": true,
"type": "string"
},
"purpose": {
"nullable": true,
"type": "string"
},
"token": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"IssueOutOfBandProofChallengeResult": {
"additionalProperties": false,
"properties": {
"challengeId": {
"format": "uuid",
"type": "string"
},
"channel": {
"$ref": "#/components/schemas/OutOfBandProofChannel"
},
"delivered": {
"type": "boolean"
},
"deliveryHint": {
"nullable": true,
"type": "string"
},
"expiresAt": {
"format": "date-time",
"type": "string"
},
"expiryConsequence": {
"nullable": true,
"type": "string"
},
"extensionsRemaining": {
"format": "int32",
"type": "integer"
},
"reused": {
"type": "boolean"
}
},
"type": "object"
},
"IssueProofChallengeRequest": {
"additionalProperties": false,
"description": "Issuance request. Carries NO destination — see the controller remarks.",
"properties": {
"caseRef": {
"description": "Opaque correlation handle for the requesting case.",
"nullable": true,
"type": "string"
},
"channel": {
"$ref": "#/components/schemas/OutOfBandProofChannel"
},
"expiryConsequence": {
"description": "REQUIRED. What the holder is told happens if the window lapses.",
"nullable": true,
"type": "string"
},
"purpose": {
"description": "Bounded slug describing why, e.g. `merge-adjudication`.",
"nullable": true,
"type": "string"
},
"subjectAccountId": {
"description": "The account whose control is being tested.",
"format": "uuid",
"type": "string"
},
"windowDays": {
"description": "Optional override of the default (7-day) window, in days.",
"format": "double",
"nullable": true,
"type": "number"
}
},
"type": "object"
},
"IssueScopedAdminGrantRequest": {
"additionalProperties": false,
"description": "Request body for issuing a scoped-admin grant, matching the org-portal's\r\n`IssueScopedAdminGrantRequest`. Deliberately carries NO issuer identity — that\r\nis resolved from the caller's JWT.",
"properties": {
"approvalPolicy": {
"description": "Kebab-case: `none` | `single-owner` | `dual-owner`.",
"nullable": true,
"type": "string"
},
"delegateName": {
"description": "Display name shown on the co-sign card.",
"nullable": true,
"type": "string"
},
"delegateRef": {
"description": "Pseudonymous reference of the staff member receiving the authority.",
"nullable": true,
"type": "string"
},
"expiresAt": {
"description": "Optional UTC expiry; null issues an open-ended grant.",
"format": "date-time",
"nullable": true,
"type": "string"
},
"justification": {
"description": "The owner's business rationale (recorded to audit).",
"nullable": true,
"type": "string"
},
"roleName": {
"description": "The scoped-role display name being granted.",
"nullable": true,
"type": "string"
},
"scopeActions": {
"description": "Action verbs the grant confers.",
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
},
"scopeModules": {
"description": "Business modules the grant reaches.",
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
}
},
"type": "object"
},
"IssueSmartLaunchContextRequest": {
"additionalProperties": false,
"description": "Wire body for minting a launch context.",
"properties": {
"clientId": {
"description": "The SMART app being launched.",
"nullable": true,
"type": "string"
},
"encounterRef": {
"description": "Opaque vendor encounter reference, when in context.",
"nullable": true,
"type": "string"
},
"iss": {
"description": "The launching EHR's FHIR base URL.",
"nullable": true,
"type": "string"
},
"lifetimeSeconds": {
"description": "Requested lifetime in seconds (30–900).",
"format": "int32",
"nullable": true,
"type": "integer"
},
"offeredScopes": {
"description": "Explicit scope array; takes precedence over Essence.Identity.Auth.Api.Controllers.IssueSmartLaunchContextRequest.Scope.",
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
},
"patientRef": {
"description": "Opaque vendor patient reference.",
"nullable": true,
"type": "string"
},
"scope": {
"description": "Space-delimited scopes the EHR authorises for this launch.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"IssueSmartLaunchContextResult": {
"additionalProperties": false,
"properties": {
"expiresAt": {
"format": "date-time",
"type": "string"
},
"launchContextId": {
"format": "uuid",
"type": "string"
},
"launchToken": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"JsonWebKey": {
"additionalProperties": false,
"description": "JSON Web Key structure (JWK).",
"properties": {
"alg": {
"description": "Algorithm (RS256).",
"nullable": true,
"type": "string"
},
"e": {
"description": "RSA public exponent (base64url encoded).",
"nullable": true,
"type": "string"
},
"kid": {
"description": "Key ID.",
"nullable": true,
"type": "string"
},
"kty": {
"description": "Key type (RSA).",
"nullable": true,
"type": "string"
},
"n": {
"description": "RSA modulus (base64url encoded).",
"nullable": true,
"type": "string"
},
"use": {
"description": "Public key use (sig = signature).",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"JwksDocument": {
"additionalProperties": false,
"description": "JSON Web Key Set document structure (RFC 7517 §5).",
"properties": {
"keys": {
"items": {
"$ref": "#/components/schemas/JsonWebKey"
},
"nullable": true,
"type": "array"
}
},
"type": "object"
},
"LoginCommand": {
"additionalProperties": false,
"properties": {
"deviceFingerprint": {
"nullable": true,
"type": "string"
},
"deviceType": {
"nullable": true,
"type": "string"
},
"email": {
"nullable": true,
"type": "string"
},
"ipAddress": {
"nullable": true,
"type": "string"
},
"passwordHash": {
"nullable": true,
"type": "string"
},
"preferEmailStepUp": {
"type": "boolean"
},
"rememberDevice": {
"type": "boolean"
},
"userAgent": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"LoginMethodDto": {
"additionalProperties": false,
"description": "A single presented login method, in presentation order.",
"properties": {
"available": {
"description": "Whether a sign-in can be completed through this method right now.\r\n \r\n\n\r\nA method used to have one state — whether it appeared at all — so a region whose national\r\nIdP is registered but not switched on here answered byte-identically to a region\r\nthat has no national IdP, and a US resident was shown a screen that said, in effect,\r\nthat no federal way into Essence exists (#12291). Those are opposite facts. A named entry\r\nwith `available: false` is the first one; no entry at all is still the second.\r\n\n\r\nAn `available: false` method must NOT be rendered as a clickable control — that is the\r\nwhole of #6945, which this does not relax: a national-IdP button carrying a placeholder\r\n`client_id` hands the person to the real IdP, which refuses on its own unbranded page\r\nwith no route back. It is rendered named, disabled and explained.\r\n\n`true` for every method the policy has always presented, so a client that does not\r\nread this field sees exactly the list it saw before.\r\n",
"type": "boolean"
},
"displayName": {
"nullable": true,
"type": "string"
},
"id": {
"nullable": true,
"type": "string"
},
"kind": {
"nullable": true,
"type": "string"
},
"provider": {
"nullable": true,
"type": "string"
},
"unavailableReason": {
"description": "Why the method is unavailable — `\"not-configured\"` (the provider is registered for\r\nthis region but this instance holds no usable credential for it, the presentation twin of\r\nthe authorize route's 501 `federated-provider-not-configured`). Null when\r\nEssence.Identity.Auth.Api.Controllers.LoginMethodDto.Available is true.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"LoginMethodsResponse": {
"additionalProperties": false,
"description": "Response for `GET /login-methods` — the ordered presentation list.",
"properties": {
"methods": {
"items": {
"$ref": "#/components/schemas/LoginMethodDto"
},
"nullable": true,
"type": "array"
},
"nationalIdp": {
"description": "What can be said about the region's national sign-in (EPIC 9 FR-09.060):\r\n`available` | `not-configured` | `none-in-region` | `region-not-stated`.\r\n`none-in-region` means the platform has no national-IdP connector for the region, which\r\nthe sign-in screen says in words — before this field that region answered with nothing, the\r\nsame blank a failed load would leave.",
"nullable": true,
"type": "string"
},
"region": {
"nullable": true,
"type": "string"
},
"socialProviders": {
"description": "The consumer social providers this instance offers at SIGN-UP (FR-44.005) — provider slugs\r\n(`Google` / `Apple` / `Microsoft`) the provider picker may present.\r\n \r\n\nAlways stated, never null. An EMPTY array means this instance offers no consumer\r\nsocial provider — either because the operator disabled them or because none holds a usable\r\ncredential — and the picker renders that as a real state. It used to carry the operator's\r\nraw allow-list, whose `null` (\"no restriction configured\") the picker read as \"offer\r\nevery provider\", so a silent instance advertised three providers it could not serve\r\n(#6527).\r\n\n\r\nThe same resolved set drives the !:LoginMethodKind.Social entries in\r\nEssence.Identity.Auth.Api.Controllers.LoginMethodsResponse.Methods, which is the SIGN-IN presentation of the same providers — so the\r\npromise onboarding makes (\"your provider can sign you back in\") cannot come apart from what\r\nthe sign-in surface offers.\r\n",
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
}
},
"type": "object"
},
"LoginResult": {
"additionalProperties": false,
"properties": {
"accessToken": {
"nullable": true,
"type": "string"
},
"accessTokenExpiresAt": {
"format": "date-time",
"type": "string"
},
"approvalRequired": {
"type": "boolean"
},
"approvalToken": {
"nullable": true,
"type": "string"
},
"deviceLimit": {
"$ref": "#/components/schemas/DeviceLimitPause"
},
"deviceLimitReached": {
"type": "boolean"
},
"dormancy": {
"$ref": "#/components/schemas/DormancyInfo"
},
"email": {
"nullable": true,
"type": "string"
},
"emailVerified": {
"type": "boolean"
},
"firstName": {
"nullable": true,
"type": "string"
},
"lastName": {
"nullable": true,
"type": "string"
},
"mfaChallengeToken": {
"nullable": true,
"type": "string"
},
"mfaCodeDelivered": {
"nullable": true,
"type": "boolean"
},
"mfaCodeDeliveryStatus": {
"nullable": true,
"type": "string"
},
"mfaCodeRetryAfterSeconds": {
"format": "int32",
"nullable": true,
"type": "integer"
},
"mfaMethod": {
"nullable": true,
"type": "string"
},
"mfaRequired": {
"type": "boolean"
},
"refreshToken": {
"nullable": true,
"type": "string"
},
"refreshTokenExpiresAt": {
"format": "date-time",
"type": "string"
},
"stepUpMethod": {
"nullable": true,
"type": "string"
},
"stepUpReason": {
"nullable": true,
"type": "string"
},
"userId": {
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"LogoutCommand": {
"additionalProperties": false,
"properties": {
"refreshToken": {
"nullable": true,
"type": "string"
},
"revokeAllSessions": {
"type": "boolean"
}
},
"type": "object"
},
"LogoutResult": {
"additionalProperties": false,
"properties": {
"sessionsRevoked": {
"format": "int32",
"type": "integer"
},
"success": {
"type": "boolean"
}
},
"type": "object"
},
"MediumEnrolmentOptionsDto": {
"additionalProperties": false,
"properties": {
"enrolledRoutes": {
"format": "int32",
"type": "integer"
},
"minimumRoutes": {
"format": "int32",
"type": "integer"
},
"requiredLevel": {
"nullable": true,
"type": "string"
},
"routes": {
"items": {
"$ref": "#/components/schemas/MediumEnrolmentRouteDto"
},
"nullable": true,
"type": "array"
}
},
"type": "object"
},
"MediumEnrolmentRouteDto": {
"additionalProperties": false,
"properties": {
"enrolled": {
"type": "boolean"
},
"level": {
"nullable": true,
"type": "string"
},
"method": {
"nullable": true,
"type": "string"
},
"notOfferedReason": {
"nullable": true,
"type": "string"
},
"offered": {
"type": "boolean"
},
"prerequisite": {
"nullable": true,
"type": "string"
},
"setUpEndpoint": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"MemberInvitationTokenRequest": {
"additionalProperties": false,
"description": "Request body for the two authenticated invitation actions. Carries the token and nothing else:\r\nthe account, the device and the session all come from the caller's JWT, so there is no field\r\nhere by which a caller could name somebody other than themselves.",
"properties": {
"token": {
"description": "The opaque token from the invitation link.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"MergePolicyDecisionInput": {
"additionalProperties": false,
"properties": {
"acknowledgedDisclosure": {
"type": "boolean"
},
"decidedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"orgName": {
"nullable": true,
"type": "string"
},
"overridden": {
"type": "boolean"
},
"reason": {
"nullable": true,
"type": "string"
},
"templateInForce": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"MergeStageProgressDto": {
"additionalProperties": false,
"properties": {
"stage": {
"nullable": true,
"type": "string"
},
"state": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"MergeStepUpDto": {
"additionalProperties": false,
"description": "A step-up factor + proof value supplied with the destructive merge confirm.",
"properties": {
"factor": {
"description": "The step-up factor name (Totp | Sms | Email | WebAuthn), case-insensitive.",
"nullable": true,
"type": "string"
},
"value": {
"description": "The proof value: an OTP code, or a WebAuthn assertion JSON payload.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"MfaMethod": {
"enum": [
0,
1,
2,
3,
4,
5
],
"format": "int32",
"type": "integer"
},
"MfaStatusDto": {
"additionalProperties": false,
"properties": {
"backupCodesIssued": {
"format": "int32",
"type": "integer"
},
"backupCodesRemaining": {
"format": "int32",
"type": "integer"
},
"emailEnabled": {
"type": "boolean"
},
"smsEnabled": {
"type": "boolean"
},
"totpEnabled": {
"type": "boolean"
}
},
"type": "object"
},
"NameBearingCredentialInput": {
"additionalProperties": false,
"properties": {
"credentialClass": {
"nullable": true,
"type": "string"
},
"credentialId": {
"format": "uuid",
"type": "string"
},
"label": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"NameChangeHistoryExport": {
"additionalProperties": false,
"properties": {
"accountId": {
"format": "uuid",
"type": "string"
},
"auditAnchorRef": {
"nullable": true,
"type": "string"
},
"auditRecordId": {
"format": "uuid",
"type": "string"
},
"committedAt": {
"format": "date-time",
"type": "string"
},
"exportedAt": {
"format": "date-time",
"type": "string"
},
"format": {
"nullable": true,
"type": "string"
},
"newNameHash": {
"nullable": true,
"type": "string"
},
"notifiedCount": {
"format": "int32",
"type": "integer"
},
"previousNameDisposition": {
"nullable": true,
"type": "string"
},
"previousNameHash": {
"nullable": true,
"type": "string"
},
"reattestedAt": {
"format": "date-time",
"type": "string"
},
"recordType": {
"nullable": true,
"type": "string"
},
"withheldCount": {
"format": "int32",
"type": "integer"
}
},
"type": "object"
},
"NewDeviceFreezeLinkRequest": {
"additionalProperties": false,
"description": "The two values the alert's link carries.",
"properties": {
"alertId": {
"description": "The alert (new-device event) id.",
"format": "uuid",
"type": "string"
},
"token": {
"description": "The link's single-use token.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"NewDeviceFreezeLinkResponse": {
"additionalProperties": false,
"description": "A live link was used: the account is frozen.",
"properties": {
"frozen": {
"type": "boolean"
}
},
"type": "object"
},
"NonCustodyAttestationDto": {
"additionalProperties": false,
"properties": {
"actionCount": {
"format": "int32",
"type": "integer"
},
"asOf": {
"format": "date-time",
"type": "string"
},
"assistantUserId": {
"format": "uuid",
"type": "string"
},
"assistedUserId": {
"format": "uuid",
"type": "string"
},
"expiresAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"grantId": {
"format": "uuid",
"type": "string"
},
"keyMaterialAccessed": {
"type": "boolean"
},
"nonCustodyAttested": {
"type": "boolean"
},
"sessionId": {
"format": "uuid",
"type": "string"
},
"statement": {
"nullable": true,
"type": "string"
},
"status": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"OAuthCallbackRequest": {
"additionalProperties": false,
"description": "Request model for OAuth callback. Carries no link target: whether a callback links, and to\r\nwhom, is decided by the one-time state (see `{provider}/link/authorize`), never the body.",
"properties": {
"authorizationCode": {
"description": "Authorization code received from the OAuth provider.",
"nullable": true,
"type": "string"
},
"codeVerifier": {
"description": "PKCE code verifier generated during authorization initiation.",
"nullable": true,
"type": "string"
},
"deviceFingerprint": {
"description": "Optional device fingerprint for device creation/tracking.",
"nullable": true,
"type": "string"
},
"homeRegion": {
"description": "Fallback sovereign home region for a NEW account (ISO 3166-1 alpha-2; FR-44.040,\r\nD-123). The region carried in the OAuth state (chosen before redirect) wins; this is\r\nused only when the state carries none. Ignored when the identity resolves to an\r\nexisting or linked account.",
"nullable": true,
"type": "string"
},
"redirectUri": {
"description": "Redirect URI used in the authorization request.\r\nMust match exactly for security.",
"nullable": true,
"type": "string"
},
"state": {
"description": "State parameter for CSRF protection.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"OAuthCallbackResult": {
"additionalProperties": false,
"properties": {
"accessToken": {
"nullable": true,
"type": "string"
},
"accessTokenExpiresAt": {
"format": "date-time",
"type": "string"
},
"accountLinked": {
"type": "boolean"
},
"deviceLimit": {
"$ref": "#/components/schemas/DeviceLimitPause"
},
"deviceLimitReached": {
"type": "boolean"
},
"email": {
"nullable": true,
"type": "string"
},
"emailVerified": {
"type": "boolean"
},
"grantedScopes": {
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
},
"homeRegion": {
"nullable": true,
"type": "string"
},
"isNewUser": {
"type": "boolean"
},
"isRelayEmail": {
"type": "boolean"
},
"mfaChallengeToken": {
"nullable": true,
"type": "string"
},
"mfaCodeDelivered": {
"nullable": true,
"type": "boolean"
},
"mfaCodeDeliveryStatus": {
"nullable": true,
"type": "string"
},
"mfaCodeRetryAfterSeconds": {
"format": "int32",
"nullable": true,
"type": "integer"
},
"mfaMethod": {
"nullable": true,
"type": "string"
},
"mfaRequired": {
"type": "boolean"
},
"name": {
"nullable": true,
"type": "string"
},
"provider": {
"nullable": true,
"type": "string"
},
"refreshToken": {
"nullable": true,
"type": "string"
},
"refreshTokenExpiresAt": {
"format": "date-time",
"type": "string"
},
"userId": {
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"OAuthLinkResult": {
"additionalProperties": false,
"description": "Response model for OAuth provider linking.",
"properties": {
"message": {
"description": "Success or error message.",
"nullable": true,
"type": "string"
},
"provider": {
"description": "Identity provider that was linked.",
"nullable": true,
"type": "string"
},
"success": {
"description": "Whether the linking was successful.",
"type": "boolean"
}
},
"type": "object"
},
"OpenBiometricReenrolmentRequest": {
"additionalProperties": false,
"description": "Body for opening a re-enrolment session (all optional — the subject is from the token).",
"properties": {
"lockoutState": {
"nullable": true,
"type": "string"
},
"memberReference": {
"nullable": true,
"type": "string"
},
"mismatchReason": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"OpenIdConfiguration": {
"additionalProperties": false,
"description": "OpenID Connect discovery document (OIDC Discovery 1.0 §3 / RFC 8414 §2).",
"properties": {
"authorization_endpoint": {
"nullable": true,
"type": "string"
},
"claims_supported": {
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
},
"id_token_signing_alg_values_supported": {
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
},
"issuer": {
"nullable": true,
"type": "string"
},
"jwks_uri": {
"nullable": true,
"type": "string"
},
"response_types_supported": {
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
},
"scopes_supported": {
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
},
"subject_types_supported": {
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
},
"token_endpoint": {
"nullable": true,
"type": "string"
},
"token_endpoint_auth_methods_supported": {
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
},
"userinfo_endpoint": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"OperatingJurisdictionEndedResponse": {
"additionalProperties": false,
"description": "A declaration that was ended early.",
"properties": {
"endedAt": {
"description": "When it was ended (UTC).",
"format": "date-time",
"type": "string"
},
"jurisdiction": {
"description": "The jurisdiction that had been in force.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"OperatingJurisdictionResponse": {
"additionalProperties": false,
"description": "The declaration as recorded on the session.",
"properties": {
"corroborated": {
"description": "Whether the request located to the same jurisdiction.",
"type": "boolean"
},
"declaredAt": {
"description": "When it was recorded (UTC).",
"format": "date-time",
"type": "string"
},
"expiresAt": {
"description": "When the session's tokens stop carrying it (UTC). Declare again to continue.",
"format": "date-time",
"type": "string"
},
"jurisdiction": {
"description": "The normalised code.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"OperationalRoleCatalogueEntryDto": {
"additionalProperties": false,
"description": "One grantable role as shown on the administration screen.",
"properties": {
"capability": {
"description": "The operational capability it belongs to.",
"nullable": true,
"type": "string"
},
"description": {
"description": "What holding it lets the person do.",
"nullable": true,
"type": "string"
},
"displayName": {
"description": "Human label.",
"nullable": true,
"type": "string"
},
"issuedThroughOrgPortal": {
"description": "The role is granted in the organisation portal's Members screen (Module roles), and a grant\r\nhere is refused with `issued-through-org-portal`. Carried on the catalogue so the\r\nadministration screen can send the administrator there instead of offering a grant that is\r\ncertain to be refused (#6191).",
"type": "boolean"
},
"role": {
"description": "The canonical kebab-case claim value.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"OrgIdpRecordDto": {
"additionalProperties": false,
"description": "Wire shape matching `orgSsoResolution.ts::OrgIdpRecord` (camel-cased by the serializer).",
"properties": {
"displayName": {
"nullable": true,
"type": "string"
},
"domain": {
"nullable": true,
"type": "string"
},
"enterpriseEntitlement": {
"type": "boolean"
},
"organizationId": {
"nullable": true,
"type": "string"
},
"protocol": {
"nullable": true,
"type": "string"
},
"provider": {
"nullable": true,
"type": "string"
},
"ssoOnly": {
"type": "boolean"
}
},
"type": "object"
},
"OrgIdpResolveResponse": {
"additionalProperties": false,
"description": "Response for `GET /org-idp/resolve`. `Org` is null when not federated.",
"properties": {
"org": {
"$ref": "#/components/schemas/OrgIdpRecordDto"
}
},
"type": "object"
},
"OrgMembershipStandingDto": {
"additionalProperties": false,
"properties": {
"activeMember": {
"type": "boolean"
},
"administers": {
"type": "boolean"
},
"organizationId": {
"format": "uuid",
"type": "string"
},
"userId": {
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"OrgOperationalRoleHolder": {
"additionalProperties": false,
"properties": {
"roles": {
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
},
"userId": {
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"OrgOperationalRoleHoldersResult": {
"additionalProperties": false,
"properties": {
"holders": {
"items": {
"$ref": "#/components/schemas/OrgOperationalRoleHolder"
},
"nullable": true,
"type": "array"
},
"membersScanned": {
"format": "int32",
"type": "integer"
},
"truncated": {
"type": "boolean"
}
},
"type": "object"
},
"OrgSsoCoverageDto": {
"additionalProperties": false,
"properties": {
"coveredDomainCount": {
"format": "int32",
"type": "integer"
},
"memberCount": {
"format": "int32",
"nullable": true,
"type": "integer"
},
"organizationId": {
"format": "uuid",
"type": "string"
},
"resolved": {
"type": "boolean"
}
},
"type": "object"
},
"OrganisationDelegateAccessPairDto": {
"additionalProperties": false,
"properties": {
"capabilities": {
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
},
"delegateLabel": {
"nullable": true,
"type": "string"
},
"delegateUserId": {
"format": "uuid",
"type": "string"
},
"delegationId": {
"format": "uuid",
"type": "string"
},
"expiresAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"grantId": {
"format": "uuid",
"type": "string"
},
"grantedAt": {
"format": "date-time",
"type": "string"
},
"lastActivityAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"principalLabel": {
"nullable": true,
"type": "string"
},
"principalUserId": {
"format": "uuid",
"type": "string"
},
"revokedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"status": {
"$ref": "#/components/schemas/DelegateAccessStatus"
},
"surface": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"OrganisationDelegateAccessPairDtoCursorResult": {
"additionalProperties": false,
"properties": {
"hasMore": {
"type": "boolean"
},
"items": {
"items": {
"$ref": "#/components/schemas/OrganisationDelegateAccessPairDto"
},
"nullable": true,
"type": "array"
},
"nextCursor": {
"nullable": true,
"type": "string"
},
"pageSize": {
"format": "int32",
"type": "integer"
},
"previousCursor": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"OrganisationNotificationAudienceDto": {
"additionalProperties": false,
"properties": {
"organisationRegion": {
"nullable": true,
"type": "string"
},
"organizationId": {
"format": "uuid",
"type": "string"
},
"recipientIds": {
"items": {
"format": "uuid",
"type": "string"
},
"nullable": true,
"type": "array"
},
"truncated": {
"type": "boolean"
}
},
"type": "object"
},
"OutOfBandProofChallengeStatus": {
"enum": [
0,
1,
2,
3,
4
],
"format": "int32",
"type": "integer"
},
"OutOfBandProofChallengeView": {
"additionalProperties": false,
"properties": {
"answeredAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"canExtend": {
"type": "boolean"
},
"caseRef": {
"nullable": true,
"type": "string"
},
"challengeId": {
"format": "uuid",
"type": "string"
},
"channel": {
"$ref": "#/components/schemas/OutOfBandProofChannel"
},
"expiresAt": {
"format": "date-time",
"type": "string"
},
"expiryConsequence": {
"nullable": true,
"type": "string"
},
"extensionsGranted": {
"format": "int32",
"type": "integer"
},
"extensionsRemaining": {
"format": "int32",
"type": "integer"
},
"issuedAt": {
"format": "date-time",
"type": "string"
},
"outcome": {
"$ref": "#/components/schemas/OutOfBandProofOutcome"
},
"purpose": {
"nullable": true,
"type": "string"
},
"resolvedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"status": {
"$ref": "#/components/schemas/OutOfBandProofChallengeStatus"
},
"subjectAccountId": {
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"OutOfBandProofChannel": {
"enum": [
0,
1
],
"format": "int32",
"type": "integer"
},
"OutOfBandProofOutcome": {
"enum": [
0,
1,
2,
3,
4
],
"format": "int32",
"type": "integer"
},
"OutcomeRequest": {
"additionalProperties": false,
"description": "Body for resolving a session terminally.",
"properties": {
"outcome": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"PartnerSupportSessionDto": {
"additionalProperties": false,
"properties": {
"agentDisplayName": {
"nullable": true,
"type": "string"
},
"agentId": {
"format": "uuid",
"type": "string"
},
"applicationId": {
"format": "uuid",
"type": "string"
},
"consentId": {
"format": "uuid",
"type": "string"
},
"endedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"expiresAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"reasonCode": {
"nullable": true,
"type": "string"
},
"scopes": {
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
},
"sessionId": {
"format": "uuid",
"type": "string"
},
"startedAt": {
"format": "date-time",
"type": "string"
},
"status": {
"nullable": true,
"type": "string"
},
"subjectUserReference": {
"nullable": true,
"type": "string"
},
"terminationReason": {
"nullable": true,
"type": "string"
},
"ticketReference": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"PasswordBreachRangeEntryDto": {
"additionalProperties": false,
"description": "One suffix of the range.",
"properties": {
"count": {
"description": "How often it occurs in the corpus; 0 marks padding.",
"format": "int32",
"type": "integer"
},
"suffix": {
"description": "The remaining 35 upper-case hex characters of a SHA-1 in the corpus.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"PasswordBreachRangeRequest": {
"additionalProperties": false,
"description": "The request body: the prefix, and nothing else.",
"properties": {
"prefix": {
"description": "The first 5 upper-case hex characters of SHA-1(password).",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"PasswordBreachRangeResponse": {
"additionalProperties": false,
"description": "The range for one prefix, padding included (wire names fixed regardless of host JSON options).",
"properties": {
"suffixes": {
"description": "Every suffix sharing the prefix.",
"items": {
"$ref": "#/components/schemas/PasswordBreachRangeEntryDto"
},
"nullable": true,
"type": "array"
}
},
"type": "object"
},
"PasswordlessLoginChallengeRequest": {
"additionalProperties": false,
"properties": {
"userVerification": {
"description": "Optional override for user verification. Defaults to `required`\r\non the command side — overriding down to `preferred` is\r\ntolerated but not encouraged.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"PasswordlessLoginChallengeResult": {
"additionalProperties": false,
"properties": {
"challenge": {
"nullable": true,
"type": "string"
},
"rpId": {
"nullable": true,
"type": "string"
},
"sessionId": {
"nullable": true,
"type": "string"
},
"timeout": {
"format": "int32",
"type": "integer"
},
"userVerification": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"PasswordlessLoginRequest": {
"additionalProperties": false,
"properties": {
"authenticatorData": {
"nullable": true,
"type": "string"
},
"clientDataJson": {
"nullable": true,
"type": "string"
},
"credentialId": {
"nullable": true,
"type": "string"
},
"sessionId": {
"nullable": true,
"type": "string"
},
"signature": {
"nullable": true,
"type": "string"
},
"userHandle": {
"description": "Base64url-encoded userHandle returned by the authenticator.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"PasswordlessLoginResult": {
"additionalProperties": false,
"properties": {
"accessToken": {
"nullable": true,
"type": "string"
},
"accessTokenExpiresAt": {
"format": "date-time",
"type": "string"
},
"deviceLimit": {
"$ref": "#/components/schemas/DeviceLimitPause"
},
"deviceLimitReached": {
"type": "boolean"
},
"errorMessage": {
"nullable": true,
"type": "string"
},
"refreshToken": {
"nullable": true,
"type": "string"
},
"refreshTokenExpiresAt": {
"format": "date-time",
"type": "string"
},
"success": {
"type": "boolean"
},
"userId": {
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"PendingCustodialOrderItem": {
"additionalProperties": false,
"properties": {
"documentName": {
"nullable": true,
"type": "string"
},
"effectiveDateIso": {
"nullable": true,
"type": "string"
},
"evidenceCodes": {
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
},
"hasDocument": {
"type": "boolean"
},
"instrumentCode": {
"nullable": true,
"type": "string"
},
"instrumentLabel": {
"nullable": true,
"type": "string"
},
"issuingAuthority": {
"nullable": true,
"type": "string"
},
"jurisdictionCode": {
"nullable": true,
"type": "string"
},
"orderId": {
"nullable": true,
"type": "string"
},
"orderReference": {
"nullable": true,
"type": "string"
},
"requiredAuthoriser": {
"nullable": true,
"type": "string"
},
"submittedAtIso": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"PendingCustodialOrderItemCursorResult": {
"additionalProperties": false,
"properties": {
"hasMore": {
"type": "boolean"
},
"items": {
"items": {
"$ref": "#/components/schemas/PendingCustodialOrderItem"
},
"nullable": true,
"type": "array"
},
"nextCursor": {
"nullable": true,
"type": "string"
},
"pageSize": {
"format": "int32",
"type": "integer"
},
"previousCursor": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"PendingDeviceApprovalDto": {
"additionalProperties": false,
"properties": {
"comparisonCode": {
"nullable": true,
"type": "string"
},
"expiresAt": {
"format": "date-time",
"type": "string"
},
"id": {
"format": "uuid",
"type": "string"
},
"newDeviceId": {
"format": "uuid",
"type": "string"
},
"requestedAt": {
"format": "date-time",
"type": "string"
},
"requesterIp": {
"nullable": true,
"type": "string"
},
"requesterUserAgent": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"PendingSupportAccessRequestDto": {
"additionalProperties": false,
"properties": {
"agentDisplayName": {
"nullable": true,
"type": "string"
},
"agentPrincipalId": {
"format": "uuid",
"type": "string"
},
"consentId": {
"format": "uuid",
"type": "string"
},
"expiresAt": {
"format": "date-time",
"type": "string"
},
"partnerAppId": {
"format": "uuid",
"type": "string"
},
"partnerApproved": {
"type": "boolean"
},
"partnerName": {
"nullable": true,
"type": "string"
},
"partnerNameStatus": {
"nullable": true,
"type": "string"
},
"publisherName": {
"nullable": true,
"type": "string"
},
"publisherVerified": {
"nullable": true,
"type": "boolean"
},
"reasonCode": {
"nullable": true,
"type": "string"
},
"requestId": {
"format": "uuid",
"type": "string"
},
"requestedAt": {
"format": "date-time",
"type": "string"
},
"requestedDurationMinutes": {
"format": "int32",
"type": "integer"
},
"requestedScopes": {
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
},
"ticketReference": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"PhoneVerificationConfirmedResponse": {
"additionalProperties": false,
"description": "The number is verified.",
"properties": {
"verified": {
"type": "boolean"
}
},
"type": "object"
},
"PhoneVerificationSentResponse": {
"additionalProperties": false,
"description": "The masked number the code went to, and when it expires.",
"properties": {
"expiresAt": {
"format": "date-time",
"type": "string"
},
"maskedNumber": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"PollDeviceApprovalResult": {
"additionalProperties": false,
"properties": {
"accessToken": {
"nullable": true,
"type": "string"
},
"accessTokenExpiresAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"comparisonCode": {
"nullable": true,
"type": "string"
},
"refreshToken": {
"nullable": true,
"type": "string"
},
"refreshTokenExpiresAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"status": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"PreAssignedRoleInput": {
"additionalProperties": false,
"properties": {
"description": {
"nullable": true,
"type": "string"
},
"name": {
"nullable": true,
"type": "string"
},
"roleId": {
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"PreferredLocaleResult": {
"additionalProperties": false,
"properties": {
"changed": {
"type": "boolean"
},
"preferredLocale": {
"nullable": true,
"type": "string"
},
"reserveAuditRef": {
"nullable": true,
"type": "string"
},
"supportedLocales": {
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
}
},
"type": "object"
},
"PrimaryContactCascadeEntry": {
"additionalProperties": false,
"properties": {
"affectedRefCount": {
"format": "int32",
"type": "integer"
},
"consumer": {
"nullable": true,
"type": "string"
},
"epic": {
"format": "int32",
"type": "integer"
},
"status": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"PrimaryContactCascadeView": {
"additionalProperties": false,
"properties": {
"changeId": {
"format": "uuid",
"type": "string"
},
"committedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"consumers": {
"items": {
"$ref": "#/components/schemas/PrimaryContactCascadeEntry"
},
"nullable": true,
"type": "array"
},
"status": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"PrimaryContactChangeView": {
"additionalProperties": false,
"properties": {
"accountId": {
"format": "uuid",
"type": "string"
},
"cancelledAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"changeId": {
"format": "uuid",
"type": "string"
},
"channel": {
"nullable": true,
"type": "string"
},
"committedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"factorsRevalidatedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"newContactMasked": {
"nullable": true,
"type": "string"
},
"previousContactMasked": {
"nullable": true,
"type": "string"
},
"recoveryFactorStates": {
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
},
"resendCount": {
"format": "int32",
"type": "integer"
},
"reverifiedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"status": {
"nullable": true,
"type": "string"
},
"trustWindowClosesAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"trustWindowOpenedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"trustedContactOfRecordMasked": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"PrincipalValidationDto": {
"additionalProperties": false,
"properties": {
"exists": {
"type": "boolean"
},
"homeRegion": {
"nullable": true,
"type": "string"
},
"isActive": {
"type": "boolean"
},
"userId": {
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"ProbateAssuranceResult": {
"additionalProperties": false,
"properties": {
"achievedAal": {
"nullable": true,
"type": "string"
},
"authorityBasis": {
"nullable": true,
"type": "string"
},
"required": {
"nullable": true,
"type": "string"
},
"shortfall": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"ProbateRoleGrantDto": {
"additionalProperties": false,
"properties": {
"attorneyUserId": {
"format": "uuid",
"type": "string"
},
"estateId": {
"format": "uuid",
"nullable": true,
"type": "string"
},
"expiresAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"grantId": {
"format": "uuid",
"type": "string"
},
"jurisdiction": {
"nullable": true,
"type": "string"
},
"poaId": {
"format": "uuid",
"nullable": true,
"type": "string"
},
"poaType": {
"nullable": true,
"type": "string"
},
"revokedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"scopeCategoryCount": {
"format": "int32",
"type": "integer"
},
"scopeDocumentCount": {
"format": "int32",
"type": "integer"
},
"scopeFieldCount": {
"format": "int32",
"type": "integer"
},
"status": {
"$ref": "#/components/schemas/ProbateRoleStatus"
}
},
"type": "object"
},
"ProbateRoleGrantResponse": {
"additionalProperties": false,
"description": "Response body for the grant call.",
"properties": {
"grantId": {
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"ProbateRoleScopeRequest": {
"additionalProperties": false,
"description": "Scope counts the grant is bounded to.",
"properties": {
"categoryCount": {
"format": "int32",
"type": "integer"
},
"documentCount": {
"format": "int32",
"type": "integer"
},
"fieldCount": {
"format": "int32",
"type": "integer"
}
},
"type": "object"
},
"ProbateRoleStatus": {
"enum": [
0,
1,
2
],
"format": "int32",
"type": "integer"
},
"ProbateStepUpChallengeResponse": {
"additionalProperties": false,
"description": "Wire response for a probate step-up challenge. Exists so `factor` leaves as\r\nthe published `phone-call`-style string rather than the enum's ordinal —\r\nthe outbound half of #8134.",
"properties": {
"deliveryHint": {
"nullable": true,
"type": "string"
},
"expiresAt": {
"format": "date-time",
"type": "string"
},
"factor": {
"nullable": true,
"type": "string"
},
"sent": {
"type": "boolean"
},
"webAuthnChallenge": {
"nullable": true,
"type": "string"
},
"webAuthnSessionId": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"ProbateStepUpResponse": {
"additionalProperties": false,
"description": "Wire response for a successful probate step-up. `authorityBasis` leaves as\r\n`court-grant` | `probate-role` — the same vocabulary the token's\r\n`authority_basis` claim and the assurance endpoint already publish, rather\r\nthan the enum's ordinal (#8134).",
"properties": {
"achievedAal": {
"nullable": true,
"type": "string"
},
"authorityBasis": {
"nullable": true,
"type": "string"
},
"estateId": {
"format": "uuid",
"type": "string"
},
"expiresAt": {
"format": "date-time",
"type": "string"
},
"maxExpiresAt": {
"format": "date-time",
"type": "string"
},
"stepUpToken": {
"nullable": true,
"type": "string"
},
"warnAt": {
"format": "date-time",
"type": "string"
}
},
"type": "object"
},
"ProblemDetails": {
"additionalProperties": {},
"properties": {
"detail": {
"nullable": true,
"type": "string"
},
"instance": {
"nullable": true,
"type": "string"
},
"status": {
"format": "int32",
"nullable": true,
"type": "integer"
},
"title": {
"nullable": true,
"type": "string"
},
"type": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"ProfessionalAdviserAuthorisationResult": {
"additionalProperties": false,
"properties": {
"adviserUserId": {
"format": "uuid",
"type": "string"
},
"agencyCapabilities": {
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
},
"agencyId": {
"format": "uuid",
"nullable": true,
"type": "string"
},
"agencyName": {
"nullable": true,
"type": "string"
},
"authorisedSince": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"caseReference": {
"nullable": true,
"type": "string"
},
"regulatedBody": {
"nullable": true,
"type": "string"
},
"verdict": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"ProfessionalAdviserRegisterResult": {
"additionalProperties": false,
"properties": {
"adviserCapabilities": {
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
},
"advisers": {
"items": {
"$ref": "#/components/schemas/ProfessionalAdviserRow"
},
"nullable": true,
"type": "array"
},
"agencyId": {
"format": "uuid",
"type": "string"
},
"agencyName": {
"nullable": true,
"type": "string"
},
"agencyStatus": {
"nullable": true,
"type": "string"
},
"authorisedCount": {
"format": "int32",
"type": "integer"
},
"organizationId": {
"format": "uuid",
"type": "string"
},
"totalCount": {
"format": "int32",
"type": "integer"
}
},
"type": "object"
},
"ProfessionalAdviserRow": {
"additionalProperties": false,
"properties": {
"adviserReference": {
"nullable": true,
"type": "string"
},
"adviserUserId": {
"format": "uuid",
"type": "string"
},
"authorised": {
"type": "boolean"
},
"liveCaseCount": {
"format": "int32",
"type": "integer"
},
"registeredAt": {
"format": "date-time",
"type": "string"
},
"regulatedBody": {
"nullable": true,
"type": "string"
},
"regulatedReference": {
"nullable": true,
"type": "string"
},
"revocationReason": {
"nullable": true,
"type": "string"
},
"revokedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"roleIssuedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"status": {
"nullable": true,
"type": "string"
},
"suspendedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"suspensionReason": {
"nullable": true,
"type": "string"
},
"verificationLevel": {
"nullable": true,
"type": "string"
},
"verifiedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"ProfessionalAttestationDto": {
"additionalProperties": false,
"properties": {
"assurance": {
"nullable": true,
"type": "string"
},
"body": {
"nullable": true,
"type": "string"
},
"credentialType": {
"nullable": true,
"type": "string"
},
"expiresAtIso": {
"nullable": true,
"type": "string"
},
"fieldKey": {
"nullable": true,
"type": "string"
},
"signingKeyId": {
"nullable": true,
"type": "string"
},
"status": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"ProfileNameResult": {
"additionalProperties": false,
"properties": {
"changed": {
"type": "boolean"
},
"editable": {
"type": "boolean"
},
"firstName": {
"nullable": true,
"type": "string"
},
"lastName": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"ProofingPolicyResult": {
"additionalProperties": false,
"properties": {
"authority": {
"nullable": true,
"type": "string"
},
"isDefault": {
"type": "boolean"
},
"proofingPolicy": {
"nullable": true,
"type": "string"
},
"subjectUserId": {
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"ProofingSessionResult": {
"additionalProperties": false,
"properties": {
"completedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"expiresAt": {
"format": "date-time",
"type": "string"
},
"failureReason": {
"nullable": true,
"type": "string"
},
"provider": {
"nullable": true,
"type": "string"
},
"reachedLevel": {
"nullable": true,
"type": "string"
},
"relyingServiceId": {
"nullable": true,
"type": "string"
},
"requiredLevel": {
"nullable": true,
"type": "string"
},
"satisfiesRequirement": {
"type": "boolean"
},
"sessionId": {
"format": "uuid",
"type": "string"
},
"shortfallReason": {
"nullable": true,
"type": "string"
},
"status": {
"nullable": true,
"type": "string"
},
"subjectUserId": {
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"ProveAccountMergeRequest": {
"additionalProperties": false,
"description": "Wire body to bind proof-of-control for one account: which account, and a second-factor\r\nproof enrolled on it. Matches the delivered client's `bindRetiring` payload.",
"properties": {
"accountId": {
"description": "Which account (retiring or surviving) this proof is for. Optional — omit it to prove\r\nthe session's retiring account, which is what the merge flow's proof step is for.",
"format": "uuid",
"nullable": true,
"type": "string"
},
"factor": {
"description": "The step-up factor name (Totp | Sms | Email | WebAuthn), case-insensitive.",
"nullable": true,
"type": "string"
},
"value": {
"description": "The proof value: an OTP code, or a WebAuthn assertion JSON payload.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"ProveAccountMergeResponse": {
"additionalProperties": false,
"properties": {
"bothAccountsProven": {
"type": "boolean"
},
"mergeSessionId": {
"format": "uuid",
"type": "string"
},
"status": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"ProvisionChildIdentityRequest": {
"additionalProperties": false,
"description": "New-legal-identity provisioning body.",
"properties": {
"authorityReference": {
"description": "The order reference the caller believes it is acting under.",
"nullable": true,
"type": "string"
},
"caseReference": {
"description": "The caller's opaque case reference. One case provisions one identity.",
"nullable": true,
"type": "string"
},
"contactEmail": {
"description": "Optional contact address for the new identity. Omit when the child is a minor\r\nwith no credentials of their own; the principal is then provisioned without a\r\nsign-in and credentials are enrolled later.",
"nullable": true,
"type": "string"
},
"passwordHash": {
"description": "Optional client-derived password hash, paired with Essence.Identity.Auth.Api.Controllers.ProvisionChildIdentityRequest.ContactEmail.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"ProvisionChildIdentityResult": {
"additionalProperties": false,
"properties": {
"alreadyProvisioned": {
"type": "boolean"
},
"caseReference": {
"nullable": true,
"type": "string"
},
"credentialsEnrolled": {
"type": "boolean"
},
"identityRef": {
"nullable": true,
"type": "string"
},
"provisionedAtIso": {
"nullable": true,
"type": "string"
},
"provisioningId": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"RaiseSupportAccessRequestBody": {
"additionalProperties": false,
"description": "Request body for raising a support-access request — `ImpersonationRequestDraft` in\r\n`partner-dashboard/src/features/support-access/types.ts`.",
"properties": {
"agentId": {
"format": "uuid",
"type": "string"
},
"appId": {
"format": "uuid",
"type": "string"
},
"durationMinutes": {
"format": "int32",
"type": "integer"
},
"reasonCode": {
"nullable": true,
"type": "string"
},
"scopes": {
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
},
"subjectUserReference": {
"nullable": true,
"type": "string"
},
"ticketReference": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"ReConsentChoiceDto": {
"additionalProperties": false,
"properties": {
"choice": {
"nullable": true,
"type": "string"
},
"grantId": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"ReassignAdviserCaseRequest": {
"additionalProperties": false,
"description": "Request body for handing a case over.",
"properties": {
"reason": {
"description": "Why the case is moving.",
"nullable": true,
"type": "string"
},
"successorAdviserUserId": {
"description": "The adviser taking the case on.",
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"ReattestVerifiedNameChangeRequest": {
"additionalProperties": false,
"description": "Wire body to re-attest the new name.",
"properties": {
"credentials": {
"description": "Optional: the name-bearing official credentials to reissue under the new name. Carried\r\nonto the 9→2 re-attestation event; the cascade is provisioned either way.",
"items": {
"$ref": "#/components/schemas/NameBearingCredentialInput"
},
"nullable": true,
"type": "array"
},
"reattestationRef": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"ReattestVerifiedNameChangeResult": {
"additionalProperties": false,
"properties": {
"changeId": {
"format": "uuid",
"type": "string"
},
"reattestedAt": {
"format": "date-time",
"type": "string"
},
"status": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"RecipientContactDto": {
"additionalProperties": false,
"properties": {
"displayName": {
"nullable": true,
"type": "string"
},
"email": {
"nullable": true,
"type": "string"
},
"exists": {
"type": "boolean"
},
"phone": {
"nullable": true,
"type": "string"
},
"userId": {
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"RecipientLookupRequest": {
"additionalProperties": false,
"description": "Request body for M:Essence.Identity.Auth.Api.Controllers.RecipientLookupController.Lookup(Essence.Identity.Auth.Api.Controllers.RecipientLookupRequest,System.Threading.CancellationToken).",
"properties": {
"email": {
"description": "The recipient's email address, as the grantor typed it.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"RecipientResolutionDto": {
"additionalProperties": false,
"properties": {
"resolved": {
"type": "boolean"
},
"userId": {
"format": "uuid",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"RecogniseAdviceAgencyRequest": {
"additionalProperties": false,
"description": "Request body for recognising an advice agency.",
"properties": {
"adviserCapabilities": {
"description": "The agency-level adviser permission ceiling. At least one.",
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
},
"agencyName": {
"description": "Institutional name, e.g. \"Citizens Advice Cardiff\".",
"nullable": true,
"type": "string"
},
"organizationId": {
"description": "The organisation the recognition attaches to.",
"format": "uuid",
"type": "string"
},
"regulatoryBody": {
"description": "The body under whose permission it advises, e.g. `FCA`.",
"nullable": true,
"type": "string"
},
"regulatoryReference": {
"description": "The agency's opaque reference with that body.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"RecogniseSafeguardingAuthorityRequest": {
"additionalProperties": false,
"description": "Request body for recognising a safeguarding authority.",
"properties": {
"authorityName": {
"description": "Institutional name, e.g. \"Office of the Public Guardian\".",
"nullable": true,
"type": "string"
},
"organizationId": {
"description": "The organisation being recognised.",
"format": "uuid",
"type": "string"
},
"statutoryReference": {
"description": "Optional reference to the instrument granting the office.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"RecordAdviserAccreditationRequest": {
"additionalProperties": false,
"description": "Request body for recording an adviser's professional accreditation.",
"properties": {
"regulatedBody": {
"description": "The adviser's regulator, e.g. `IMA` or `FCA`.",
"nullable": true,
"type": "string"
},
"regulatedReference": {
"description": "Their opaque reference with that body.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"RecordAssistActionRequest": {
"additionalProperties": false,
"description": "Wire body for recording a delegate-attributed assist action.",
"properties": {
"actionType": {
"nullable": true,
"type": "string"
},
"sessionId": {
"format": "uuid",
"type": "string"
},
"targetRef": {
"nullable": true,
"type": "string"
},
"touchedKeyMaterial": {
"type": "boolean"
}
},
"type": "object"
},
"RecordAssistActionResponse": {
"additionalProperties": false,
"description": "Response body for the action call.",
"properties": {
"actionId": {
"format": "uuid",
"type": "string"
},
"sessionId": {
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"RecordAssuranceRequest": {
"additionalProperties": false,
"description": "Body for recording first-run assurance (capability (a)+(b)).",
"properties": {
"emailVerified": {
"description": "Whether the account's email is verified (the LOA1 precondition). Defaults true.",
"type": "boolean"
},
"invitedByOrg": {
"description": "Whether the account is onboarding under an org invitation.",
"type": "boolean"
},
"orgName": {
"description": "Inviting organisation display name (for the authority label).",
"nullable": true,
"type": "string"
},
"proofingCompleted": {
"description": "Refused when true with 403 `proofing-outcome-not-adjudicated` (#14295): the\r\nsubject cannot certify its own proofing. Completion is recorded only by a\r\nprovider-adjudicated proofing session.",
"type": "boolean"
},
"proofingPolicy": {
"description": "Explicit proofing policy (`required`|`deferred`|`optional`); null → per-actor default.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"RecordRecoveryDecisionRequest": {
"additionalProperties": false,
"description": "Body for recording the first-run recovery decision (debt-2026-07-09-022).",
"properties": {
"recoverySetUp": {
"description": "True if the holder set up account recovery; false if they deferred it.",
"type": "boolean"
}
},
"type": "object"
},
"RecordTakeoverProgressRequest": {
"additionalProperties": false,
"description": "Request body for reporting a completed takeover-recovery step (#7393).",
"properties": {
"count": {
"description": "For `shares-revoked`: how many shares were revoked.",
"format": "int32",
"nullable": true,
"type": "integer"
},
"step": {
"description": "One of `keys-rotated`, `shares-revoked`, `closed`.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"RecordVerificationRequest": {
"additionalProperties": false,
"description": "Request body for recording an org member verification into the cohort.",
"properties": {
"checkType": {
"nullable": true,
"type": "string"
},
"subjectReference": {
"nullable": true,
"type": "string"
},
"validFrom": {
"format": "date-time",
"type": "string"
},
"validUntil": {
"format": "date-time",
"type": "string"
}
},
"type": "object"
},
"RecoveryOtpRequestDto": {
"additionalProperties": false,
"description": "Wire body for `POST /auth/mfa/otp/request`.",
"properties": {
"action": {
"description": "The step-up action discriminator; must be \"recovery-initiate\".",
"nullable": true,
"type": "string"
},
"channel": {
"description": "The recovery channel: \"email\" or \"sms\".",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"RecoveryOtpRequestResponse": {
"additionalProperties": false,
"description": "Response for a recovery OTP request — mirrors the client's expected shape.",
"properties": {
"maskedDestination": {
"nullable": true,
"type": "string"
},
"sent": {
"type": "boolean"
}
},
"type": "object"
},
"RecoveryOtpVerifyDto": {
"additionalProperties": false,
"description": "Wire body for `POST /auth/mfa/otp/verify`.",
"properties": {
"action": {
"description": "The step-up action discriminator; must be \"recovery-initiate\".",
"nullable": true,
"type": "string"
},
"channel": {
"description": "The recovery channel: \"email\" or \"sms\".",
"nullable": true,
"type": "string"
},
"code": {
"description": "The one-time code the user received.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"RecoveryOtpVerifyResponse": {
"additionalProperties": false,
"description": "Response for a recovery OTP verify — mirrors the client's `MfaVerifyResponse`.",
"properties": {
"expiresAt": {
"description": "Absolute UTC expiry of StepUpToken.",
"format": "date-time",
"nullable": true,
"type": "string"
},
"stepUpToken": {
"description": "The FR-01.045 `aal=2` / `act=recovery-initiate` elevation token to present\r\nas `stepUpToken` on `POST /api/v1/recovery/initiate`. Null when\r\nVerified is false (debt-2026-08-24-055 — before this, the surface\r\nconfirmed the proof and handed back nothing the recovery endpoint could consume).",
"nullable": true,
"type": "string"
},
"verified": {
"description": "Whether the delivered code matched.",
"type": "boolean"
}
},
"type": "object"
},
"RecoveryPhraseTokenRequest": {
"additionalProperties": false,
"description": "Request body for `POST /recovery-phrase/token` — the anonymous recovery entry for a\r\nuser who has forgotten their password. Essence.Identity.Auth.Api.Controllers.RecoveryPhraseTokenRequest.RecoveryProof is the client-derived\r\nrecovery proof (hex, ≥ 64 chars) — never the phrase.",
"properties": {
"email": {
"nullable": true,
"type": "string"
},
"recoveryProof": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"RecoveryRewrapTokenResponse": {
"additionalProperties": false,
"description": "Response for `POST /recovery-phrase/token`: the one-shot, 5-minute\r\n`purpose=recovery-rewrap` token and its absolute UTC expiry. Carries no key material.",
"properties": {
"expiresAt": {
"format": "date-time",
"type": "string"
},
"purpose": {
"nullable": true,
"type": "string"
},
"token": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"RefreshTokenCommand": {
"additionalProperties": false,
"properties": {
"deviceFingerprint": {
"nullable": true,
"type": "string"
},
"ipAddress": {
"nullable": true,
"type": "string"
},
"refreshToken": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"RefreshTokenResult": {
"additionalProperties": false,
"properties": {
"accessToken": {
"nullable": true,
"type": "string"
},
"accessTokenExpiresAt": {
"format": "date-time",
"type": "string"
},
"refreshToken": {
"nullable": true,
"type": "string"
},
"refreshTokenExpiresAt": {
"format": "date-time",
"type": "string"
}
},
"type": "object"
},
"RegenerateMfaBackupCodesResult": {
"additionalProperties": false,
"properties": {
"backupCodes": {
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
},
"message": {
"nullable": true,
"type": "string"
},
"success": {
"type": "boolean"
}
},
"type": "object"
},
"RegisterDelegatedAgentRequest": {
"additionalProperties": false,
"description": "Request body for agent registration.",
"properties": {
"consentGrantId": {
"description": "EPIC 6 grant the agent acts under, when consent-backed.",
"format": "uuid",
"nullable": true,
"type": "string"
},
"grantedScopes": {
"description": "Scope slugs the delegation conveys.",
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
},
"name": {
"description": "Name the principal recognises the agent by.",
"nullable": true,
"type": "string"
},
"organisationId": {
"description": "Governing organisation, when there is one.",
"format": "uuid",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"RegisterDelegatedAgentResponse": {
"additionalProperties": false,
"description": "Registration response. The secret appears here and nowhere else, ever.",
"properties": {
"agentId": {
"description": "The aggregate id.",
"format": "uuid",
"type": "string"
},
"agentReference": {
"description": "The opaque cross-service reference.",
"nullable": true,
"type": "string"
},
"secret": {
"description": "The credential secret. Store it now; it cannot be retrieved.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"RegisterOrgInvitationCommand": {
"additionalProperties": false,
"properties": {
"department": {
"nullable": true,
"type": "string"
},
"expiresAt": {
"format": "date-time",
"type": "string"
},
"homeRegion": {
"nullable": true,
"type": "string"
},
"invitationId": {
"format": "uuid",
"type": "string"
},
"invitedByDisplayName": {
"nullable": true,
"type": "string"
},
"invitedByUserId": {
"format": "uuid",
"type": "string"
},
"inviteeEmail": {
"nullable": true,
"type": "string"
},
"organizationId": {
"format": "uuid",
"type": "string"
},
"organizationName": {
"nullable": true,
"type": "string"
},
"preAssignedRoles": {
"items": {
"$ref": "#/components/schemas/PreAssignedRoleInput"
},
"nullable": true,
"type": "array"
},
"requireMfa": {
"type": "boolean"
},
"requireRecoverySetup": {
"type": "boolean"
},
"sponsoredPremium": {
"$ref": "#/components/schemas/SponsoredPremiumInput"
},
"token": {
"nullable": true,
"type": "string"
},
"vaultScope": {
"$ref": "#/components/schemas/VaultScopeInput"
}
},
"type": "object"
},
"RegisterOrgInvitationResult": {
"additionalProperties": false,
"properties": {
"alreadyExisted": {
"type": "boolean"
},
"invitationId": {
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"RegisterProfessionalAdviserRequest": {
"additionalProperties": false,
"description": "Request body for registering an adviser.",
"properties": {
"adviserReference": {
"description": "Opaque, agency-chosen, non-PII reference (a staff number).",
"nullable": true,
"type": "string"
},
"adviserUserId": {
"description": "The adviser's user-principal id.",
"format": "uuid",
"type": "string"
},
"regulatedBody": {
"description": "The adviser's own regulator, when known at registration.",
"nullable": true,
"type": "string"
},
"regulatedReference": {
"description": "Their opaque reference with that regulator.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"RegisterTrustedEhrIssuerRequest": {
"additionalProperties": false,
"description": "Wire body for registering a trusted EHR issuer.",
"properties": {
"allowedClientIds": {
"description": "SMART app client ids permitted to launch from this issuer.",
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
},
"displayName": {
"description": "Operator-facing vendor or instance name.",
"nullable": true,
"type": "string"
},
"grantableScopes": {
"description": "The ceiling of scopes launches from this issuer may obtain.",
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
},
"iss": {
"description": "The EHR's FHIR base URL.",
"nullable": true,
"type": "string"
},
"organizationId": {
"description": "Owning organisation, when org-scoped.",
"format": "uuid",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"RegisterTrustedEhrIssuerResponse": {
"additionalProperties": false,
"description": "Response to a trusted-issuer registration.",
"properties": {
"issuerId": {
"description": "Identifier of the registration.",
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"RegisterUserCommand": {
"additionalProperties": false,
"properties": {
"breachCheck": {
"nullable": true,
"type": "string"
},
"deviceFingerprint": {
"nullable": true,
"type": "string"
},
"deviceType": {
"nullable": true,
"type": "string"
},
"email": {
"nullable": true,
"type": "string"
},
"firstName": {
"nullable": true,
"type": "string"
},
"homeRegion": {
"nullable": true,
"type": "string"
},
"ipAddress": {
"nullable": true,
"type": "string"
},
"lastName": {
"nullable": true,
"type": "string"
},
"passwordHash": {
"nullable": true,
"type": "string"
},
"passwordPolicyVersion": {
"format": "int32",
"nullable": true,
"type": "integer"
},
"phoneNumber": {
"nullable": true,
"type": "string"
},
"proofOfWork": {
"$ref": "#/components/schemas/SignUpProofOfWork"
},
"userAgent": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"RegisterUserResult": {
"additionalProperties": false,
"properties": {
"accessToken": {
"nullable": true,
"type": "string"
},
"accessTokenExpiresAt": {
"format": "date-time",
"type": "string"
},
"email": {
"nullable": true,
"type": "string"
},
"emailVerified": {
"type": "boolean"
},
"refreshToken": {
"nullable": true,
"type": "string"
},
"refreshTokenExpiresAt": {
"format": "date-time",
"type": "string"
},
"userId": {
"format": "uuid",
"type": "string"
},
"verificationPending": {
"type": "boolean"
}
},
"type": "object"
},
"RegistrationAcceptedResponse": {
"additionalProperties": false,
"description": "The uniform body of `POST /register` (#7225). There is exactly one value, so a free\r\naddress and a taken one serialise to the same bytes.",
"properties": {
"next": {
"description": "The step the caller goes to next: always `verify-email`.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"RemoveExecutorOfficerRequest": {
"additionalProperties": false,
"description": "Request body for removing an officer from the roster.",
"properties": {
"reason": {
"description": "Why the officer was removed. Travels with the cascade onto every estate they held, so it is the\r\nonly explanation a later auditor sees for why those assignments ended.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"RenameWebAuthnCredentialRequest": {
"additionalProperties": false,
"description": "Request body for renaming a passkey.",
"properties": {
"name": {
"description": "New user-facing name for the passkey.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"RequestAccountMergeApprovalRequestBody": {
"additionalProperties": false,
"description": "Wire body to enqueue a merge for org approval (EPIC 7 governance seam,\r\ndebt-2026-07-09-284): names the organisation whose require-approval policy gates it.",
"properties": {
"organizationId": {
"description": "The organisation whose require-approval policy gates this merge.",
"format": "uuid",
"type": "string"
},
"policyDecision": {
"$ref": "#/components/schemas/MergePolicyDecisionInput"
}
},
"type": "object"
},
"RequestAccountMergeApprovalResponse": {
"additionalProperties": false,
"description": "The result of enqueuing a merge for org approval: the merge session, its lifecycle\r\nstatus, its new approval status (`Pending`), and the approving organisation.",
"properties": {
"approvalStatus": {
"nullable": true,
"type": "string"
},
"mergeSessionId": {
"format": "uuid",
"type": "string"
},
"organizationId": {
"format": "uuid",
"type": "string"
},
"status": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"RequestPrimaryContactChangeRequest": {
"additionalProperties": false,
"description": "Wire body to request a primary-contact change.",
"properties": {
"affectedConsentRefs": {
"description": "Opaque consent-grant references EPIC 6 must re-validate on cutover.",
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
},
"channel": {
"description": "`Email` or `Phone`.",
"nullable": true,
"type": "string"
},
"currentContact": {
"description": "Plaintext current primary contact — hashed + masked, then discarded.",
"nullable": true,
"type": "string"
},
"newContact": {
"description": "Plaintext new primary contact — hashed + masked, then discarded.",
"nullable": true,
"type": "string"
},
"syncedConnectionRefs": {
"description": "Opaque synced-connection references EPIC 19 must repoint on cutover.",
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
}
},
"type": "object"
},
"RequestPrimaryContactChangeResult": {
"additionalProperties": false,
"properties": {
"changeId": {
"format": "uuid",
"type": "string"
},
"newContactMasked": {
"nullable": true,
"type": "string"
},
"status": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"RequestVerifiedNameChangeRequest": {
"additionalProperties": false,
"description": "Wire body to open a verified-name-change.",
"properties": {
"affectedConsentRefs": {
"description": "Opaque consent-grant references EPIC 6 evaluates for the recipient split.",
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
},
"deedPollDocumentId": {
"description": "Optional reference to the deed-poll / legal instrument evidencing the change. Echoed on\r\nthe change record and carried onto the credential-reissue cascade as its evidence.",
"format": "uuid",
"nullable": true,
"type": "string"
},
"newNameHash": {
"description": "Client-computed SHA-256 hash (lowercase hex) of the NEW verified name.",
"nullable": true,
"type": "string"
},
"newNameMasked": {
"description": "Irreversible masked display hint of the NEW name (e.g. `J••• S•••`).",
"nullable": true,
"type": "string"
},
"previousNameDisposition": {
"description": "`KeepAlias`, `Redact` or `FormerlyKnownAs` (default).",
"nullable": true,
"type": "string"
},
"previousNameHash": {
"description": "Client-computed SHA-256 hash (lowercase hex) of the OLD verified name.",
"nullable": true,
"type": "string"
},
"previousNameMasked": {
"description": "Optional irreversible masked display hint of the PREVIOUS name (e.g. `J••• H•••`),\r\nso a surface can state both halves of the change rather than falling back to literals.",
"nullable": true,
"type": "string"
},
"syncedConnectionRefs": {
"description": "Opaque synced-connection references EPIC 19 must update on commit.",
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
}
},
"type": "object"
},
"RequestVerifiedNameChangeResult": {
"additionalProperties": false,
"properties": {
"changeId": {
"format": "uuid",
"type": "string"
},
"newNameMasked": {
"nullable": true,
"type": "string"
},
"previousNameMasked": {
"nullable": true,
"type": "string"
},
"status": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"RequiredFactorsResponse": {
"additionalProperties": false,
"description": "The factors available for step-up for the calling session.",
"properties": {
"factors": {
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
}
},
"type": "object"
},
"ResendEmailVerificationOtpByEmailRequest": {
"additionalProperties": false,
"description": "Request body for `POST /email/resend-otp/by-email` (#7539).",
"properties": {
"email": {
"description": "The address to send a fresh verification code to.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"ResendEmailVerificationOtpResult": {
"additionalProperties": false,
"properties": {
"expiresAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"message": {
"nullable": true,
"type": "string"
},
"sent": {
"type": "boolean"
}
},
"type": "object"
},
"ResendKeyClaimCodeResult": {
"additionalProperties": false,
"properties": {
"challengeId": {
"format": "uuid",
"type": "string"
},
"claimId": {
"format": "uuid",
"type": "string"
},
"resendCount": {
"format": "int32",
"type": "integer"
}
},
"type": "object"
},
"ResendLoginMfaCodeCommand": {
"additionalProperties": false,
"properties": {
"challengeToken": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"ResendLoginMfaCodeResult": {
"additionalProperties": false,
"properties": {
"message": {
"nullable": true,
"type": "string"
},
"retryAfterSeconds": {
"format": "int32",
"nullable": true,
"type": "integer"
},
"sent": {
"type": "boolean"
},
"status": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"ResendPrimaryContactChallengeRequest": {
"additionalProperties": false,
"description": "Wire body to resend the challenge (re-supply the new contact).",
"properties": {
"newContact": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"ResendPrimaryContactChallengeResult": {
"additionalProperties": false,
"properties": {
"changeId": {
"format": "uuid",
"type": "string"
},
"resendCount": {
"format": "int32",
"type": "integer"
},
"status": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"ResolveReturningNationalBootstrapRequest": {
"additionalProperties": false,
"description": "Request body for a business-admin resolution of a held bootstrap case.",
"properties": {
"action": {
"nullable": true,
"type": "string"
},
"creditLevel": {
"nullable": true,
"type": "string"
},
"note": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"ReturningNationalReceiptResult": {
"additionalProperties": false,
"properties": {
"decidedAt": {
"format": "date-time",
"type": "string"
},
"decision": {
"nullable": true,
"type": "string"
},
"decisionBasis": {
"nullable": true,
"type": "string"
},
"decisionId": {
"format": "uuid",
"type": "string"
},
"foreignLoa": {
"nullable": true,
"type": "string"
},
"intakeId": {
"nullable": true,
"type": "string"
},
"mappedDomesticAssurance": {
"nullable": true,
"type": "string"
},
"matchedPriorSovereignVaultRef": {
"nullable": true,
"type": "string"
},
"originJurisdiction": {
"nullable": true,
"type": "string"
},
"originScheme": {
"nullable": true,
"type": "string"
},
"policyId": {
"nullable": true,
"type": "string"
},
"ranIdentityCheck": {
"type": "boolean"
},
"residualCheckRequired": {
"type": "boolean"
},
"resolvedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"subjectUserId": {
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"RevalidatePrimaryContactFactorsRequest": {
"additionalProperties": false,
"description": "Wire body to re-validate recovery factors.",
"properties": {
"factorStates": {
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
}
},
"type": "object"
},
"RevalidatePrimaryContactFactorsResult": {
"additionalProperties": false,
"properties": {
"changeId": {
"format": "uuid",
"type": "string"
},
"factorsRevalidatedAt": {
"format": "date-time",
"type": "string"
},
"recoveryFactorStates": {
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
},
"status": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"ReverseMergeResponse": {
"additionalProperties": false,
"description": "The reversal receipt returned by `POST /api/v1/account/merge/{id}/reverse` — the\r\nexact shape the delivered client's `ReverseMergeResult` renders on the Step-7\r\n\"Undo merge\" affordance (debt-2026-07-07-104).",
"properties": {
"auditRef": {
"description": "Audit anchor reference for the reversal record (EPIC 4 / 12).",
"nullable": true,
"type": "string"
},
"grantsReverted": {
"description": "Number of repointed grants reverted onto the restored account.",
"format": "int32",
"type": "integer"
},
"noticesRetracted": {
"description": "Number of org notices retracted by the reversal.",
"format": "int32",
"type": "integer"
},
"restoredAccountId": {
"description": "The account restored by the reversal (previously retired).",
"format": "uuid",
"type": "string"
},
"reversedAt": {
"description": "UTC instant the reversal was recorded.",
"format": "date-time",
"type": "string"
},
"survivorAccountId": {
"description": "The surviving account retained after the reversal.",
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"RevocationProofDto": {
"additionalProperties": false,
"properties": {
"exportable": {
"type": "boolean"
},
"revocationDateIso": {
"nullable": true,
"type": "string"
},
"revocationProofRef": {
"nullable": true,
"type": "string"
},
"revokedGuardianIds": {
"items": {
"format": "uuid",
"type": "string"
},
"nullable": true,
"type": "array"
},
"subjectId": {
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"RevocationSnapshotDto": {
"additionalProperties": false,
"properties": {
"entries": {
"items": {
"$ref": "#/components/schemas/RevocationSnapshotEntryDto"
},
"nullable": true,
"type": "array"
},
"generatedAt": {
"format": "date-time",
"type": "string"
}
},
"type": "object"
},
"RevocationSnapshotEntryDto": {
"additionalProperties": false,
"properties": {
"expiresAt": {
"format": "date-time",
"type": "string"
},
"tokenId": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"RevokeAllSessionsResult": {
"additionalProperties": false,
"properties": {
"message": {
"nullable": true,
"type": "string"
},
"sessionsRevoked": {
"format": "int32",
"type": "integer"
},
"success": {
"type": "boolean"
}
},
"type": "object"
},
"RevokeAssistRequestBody": {
"additionalProperties": false,
"description": "Request body for revoking a grant.",
"properties": {
"reason": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"RevokeAssistResult": {
"additionalProperties": false,
"properties": {
"alreadyRevoked": {
"type": "boolean"
},
"grantId": {
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"RevokeDelegateAccessRequestBody": {
"additionalProperties": false,
"description": "Request body for revoking a grant.",
"properties": {
"reason": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"RevokeDelegateAccessResult": {
"additionalProperties": false,
"properties": {
"alreadyRevoked": {
"type": "boolean"
},
"grantId": {
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"RevokeProbateRoleRequest": {
"additionalProperties": false,
"description": "Request body for revoking a grant.",
"properties": {
"reason": {
"nullable": true,
"type": "string"
},
"revokedByUserId": {
"description": "Optional explicit revoking-party attribution, mirroring\r\nEssence.Identity.Auth.Api.Controllers.GrantProbateRoleRequest.GrantedByUserId. Additive and optional:\r\nan org-portal caller omits it and keeps attributing to its own claims.",
"format": "uuid",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"RevokeProbateRoleResult": {
"additionalProperties": false,
"properties": {
"grantId": {
"format": "uuid",
"type": "string"
},
"revoked": {
"type": "boolean"
}
},
"type": "object"
},
"RevokeSessionResult": {
"additionalProperties": false,
"properties": {
"message": {
"nullable": true,
"type": "string"
},
"success": {
"type": "boolean"
}
},
"type": "object"
},
"RevokeSharedDeviceRequest": {
"additionalProperties": false,
"description": "Revocation body.",
"properties": {
"reason": {
"description": "Optional: why, e.g. \"stolen from the Leeds branch\".",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"RevokeWearableSessionRequest": {
"additionalProperties": false,
"description": "Request body for scope-revoking a single lost companion watch's delegated session.\r\nThe subject is always the authenticated caller (from the JWT), never the body.",
"properties": {
"delegateFrom": {
"description": "The phone principal the watch token was delegated from (FR-65.051); optional.",
"format": "uuid",
"nullable": true,
"type": "string"
},
"reason": {
"description": "Non-PII reason token (e.g. `reported-lost`). Defaults server-side when omitted.",
"nullable": true,
"type": "string"
},
"watchDeviceId": {
"description": "Stable id of the paired watch device to sign out.",
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"RevokeWearableSessionResult": {
"additionalProperties": false,
"properties": {
"boundedInertBy": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"revoked": {
"type": "boolean"
},
"revokedAt": {
"format": "date-time",
"type": "string"
}
},
"type": "object"
},
"RotateSharedDeviceKeyRequest": {
"additionalProperties": false,
"description": "Key-rotation body.",
"properties": {
"publicKeyJwk": {
"description": "The machine's new EC P-256 public JWK, as a JSON string.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"SafeguardingAuthorityRow": {
"additionalProperties": false,
"properties": {
"authorityId": {
"format": "uuid",
"type": "string"
},
"authorityName": {
"nullable": true,
"type": "string"
},
"isRecognised": {
"type": "boolean"
},
"organizationId": {
"format": "uuid",
"type": "string"
},
"recognisedAt": {
"format": "date-time",
"type": "string"
},
"status": {
"nullable": true,
"type": "string"
},
"statusChangedAt": {
"format": "date-time",
"type": "string"
},
"statusReason": {
"nullable": true,
"type": "string"
},
"statutoryReference": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"SafeguardingOfficerAuthorisationResult": {
"additionalProperties": false,
"properties": {
"authorised": {
"type": "boolean"
},
"authorisedSince": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"officerUserId": {
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"SafeguardingOfficerRegisterResult": {
"additionalProperties": false,
"properties": {
"authorisedCount": {
"format": "int32",
"type": "integer"
},
"authorityId": {
"format": "uuid",
"type": "string"
},
"authorityName": {
"nullable": true,
"type": "string"
},
"authorityStatus": {
"nullable": true,
"type": "string"
},
"officers": {
"items": {
"$ref": "#/components/schemas/SafeguardingOfficerRow"
},
"nullable": true,
"type": "array"
},
"organizationId": {
"format": "uuid",
"type": "string"
},
"totalCount": {
"format": "int32",
"type": "integer"
}
},
"type": "object"
},
"SafeguardingOfficerRow": {
"additionalProperties": false,
"properties": {
"authorised": {
"type": "boolean"
},
"designatedAt": {
"format": "date-time",
"type": "string"
},
"officerReference": {
"nullable": true,
"type": "string"
},
"officerUserId": {
"format": "uuid",
"type": "string"
},
"revocationReason": {
"nullable": true,
"type": "string"
},
"revokedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"roleIssuedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"status": {
"nullable": true,
"type": "string"
},
"suspendedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"suspensionReason": {
"nullable": true,
"type": "string"
},
"verificationLevel": {
"nullable": true,
"type": "string"
},
"verifiedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"SendEmailOtpResult": {
"additionalProperties": false,
"properties": {
"expiresAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"message": {
"nullable": true,
"type": "string"
},
"retryAfterSeconds": {
"format": "int32",
"nullable": true,
"type": "integer"
},
"sent": {
"type": "boolean"
},
"status": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"SendProbateStepUpChallengeRequest": {
"additionalProperties": false,
"description": "Request body for issuing a probate step-up challenge. `factor` carries the\r\ncontract's kebab-case wire value (`email` | `sms` | `webauthn` |\r\n`phone-call` | `postal-code`) — a `string`, not the domain enum,\r\nbecause this service registers no global `JsonStringEnumConverter` and an\r\nenum property would bind only integer ordinals (#8134).",
"properties": {
"estateId": {
"format": "uuid",
"type": "string"
},
"factor": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"SendSmsOtpResult": {
"additionalProperties": false,
"properties": {
"expiresAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"message": {
"nullable": true,
"type": "string"
},
"retryAfterSeconds": {
"format": "int32",
"nullable": true,
"type": "integer"
},
"sent": {
"type": "boolean"
},
"status": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"SessionDto": {
"additionalProperties": false,
"properties": {
"accessTokenExpiresAt": {
"format": "date-time",
"type": "string"
},
"createdAt": {
"format": "date-time",
"type": "string"
},
"deviceFriendlyName": {
"nullable": true,
"type": "string"
},
"deviceId": {
"format": "uuid",
"type": "string"
},
"deviceType": {
"$ref": "#/components/schemas/DeviceType"
},
"id": {
"format": "uuid",
"type": "string"
},
"ipAddress": {
"nullable": true,
"type": "string"
},
"isActive": {
"type": "boolean"
},
"isCurrent": {
"type": "boolean"
},
"lastRefreshAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"lastRefreshIpAddress": {
"nullable": true,
"type": "string"
},
"refreshTokenExpiresAt": {
"format": "date-time",
"type": "string"
},
"status": {
"$ref": "#/components/schemas/SessionStatus"
},
"userAgent": {
"nullable": true,
"type": "string"
},
"userId": {
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"SessionMeResponse": {
"additionalProperties": false,
"description": "Response DTO for the session identity endpoint.",
"properties": {
"accessToken": {
"description": "ESS-QA-007 (sovereign-routing reload fix): a fresh SHORT-LIVED access token\r\nminted from the cookie-authenticated principal. The SPA holds it in memory\r\nonly (never persisted) to (a) route data-plane calls to the user's\r\nsovereign edge via its `home_region` claim and (b) present a\r\ncross-origin bearer to that edge. Null when the account could not be\r\nresolved to mint a token (the client then falls back to cookie-only mode).",
"nullable": true,
"type": "string"
},
"accessTokenExpiresAt": {
"description": "Absolute expiry (UTC) of Essence.Identity.Auth.Api.Controllers.SessionMeResponse.AccessToken, so the client can\r\nproactively re-exchange the cookie for a fresh token before it lapses.",
"format": "date-time",
"nullable": true,
"type": "string"
},
"email": {
"nullable": true,
"type": "string"
},
"emailVerified": {
"description": "ESS-QA-007 (I-3): whether the account's email is verified. Sourced from\r\nthe `email_verified` JWT claim. Lets a cookie-mode reload restore\r\nthe client's `emailVerified` flag so a verified user is not wrongly\r\nre-routed to verify-email.",
"type": "boolean"
},
"firstName": {
"nullable": true,
"type": "string"
},
"hasPassword": {
"description": "True when the account has a client-side password set. False for\r\nsocial/passkey-only accounts.",
"type": "boolean"
},
"homeRegion": {
"description": "The user's home sovereign region (e.g. `GB`) — the routing pointer,\r\nnon-PII — matching the `home_region` claim on Essence.Identity.Auth.Api.Controllers.SessionMeResponse.AccessToken.\r\nNull when no token was minted.",
"nullable": true,
"type": "string"
},
"instanceId": {
"nullable": true,
"type": "string"
},
"isPasswordless": {
"description": "True when the account has no password but at least one passkey — i.e. it\r\ncan authenticate without a password.",
"type": "boolean"
},
"lastName": {
"nullable": true,
"type": "string"
},
"onboardingPending": {
"description": "ESS-QA-007 (I-3): whether first-run onboarding is still pending. Now\r\nmeans \"email not yet verified\" (computed as `!EmailVerified`) — the\r\nonly server-sourced onboarding gate a reload must honour. The account\r\nsetup checklist (password / passkeys / MFA / recovery) reads\r\nEssence.Identity.Auth.Api.Controllers.SessionMeResponse.SetupPosture instead, so an email-verified user with an\r\nincomplete setup is never re-gated to the onboarding wizard.",
"type": "boolean"
},
"organizationId": {
"description": "The organisation this session is scoped to, resolved from the token's canonical\r\norganisation claim (Essence.Platform.Infrastructure.Security.OrgClaims.ClaimNames). `null` means the session has\r\nno organisation — a personal account — and nothing else: a token whose aliases disagree is\r\nrefused by the action rather than reported here as absent (#13852).",
"nullable": true,
"type": "string"
},
"passkeyCount": {
"description": "Number of active WebAuthn/passkey credentials enrolled.",
"format": "int32",
"type": "integer"
},
"role": {
"nullable": true,
"type": "string"
},
"roles": {
"description": "Every role the session's token carries, in claim order (#13747). Essence.Identity.Auth.Api.Controllers.SessionMeResponse.Role is only\r\nthe first of them, so a client that gates on it cannot see a second role: a platform admin\r\nwho is also granted `identity-authority` was refused the custodial-order console that\r\nthe server would have served them. Empty for an account with no role.",
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
},
"setupPosture": {
"$ref": "#/components/schemas/SetupPostureDto"
},
"userId": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"SessionStatus": {
"enum": [
0,
1,
2,
3
],
"format": "int32",
"type": "integer"
},
"SetAdviceAgencyCapabilitiesRequest": {
"additionalProperties": false,
"description": "Request body for replacing an agency's adviser permission ceiling.",
"properties": {
"adviserCapabilities": {
"description": "The replacement set. At least one.",
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
}
},
"type": "object"
},
"SetOperationalRoleRequest": {
"additionalProperties": false,
"description": "Request body for a grant. Carries no organisation — that comes from the route.",
"properties": {
"role": {
"description": "A catalogue role value.",
"nullable": true,
"type": "string"
},
"userId": {
"description": "The member receiving the role.",
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"SetOrgOperationalRoleOutcome": {
"enum": [
0,
1,
2,
3,
4,
5,
6,
7,
8
],
"format": "int32",
"type": "integer"
},
"SetOrgOperationalRoleResult": {
"additionalProperties": false,
"properties": {
"operationalRoles": {
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
},
"outcome": {
"$ref": "#/components/schemas/SetOrgOperationalRoleOutcome"
}
},
"type": "object"
},
"SetPasswordRequest": {
"additionalProperties": false,
"description": "Request body for `POST /password/set`. Essence.Identity.Auth.Api.Controllers.SetPasswordRequest.PasswordHash is the\r\nclient-derived hash (as on `register`) — never a plaintext password.",
"properties": {
"passwordHash": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"SetPreferredLocaleRequest": {
"additionalProperties": false,
"description": "Body for `PUT /api/v1/users/me/locale` and `PUT /api/v1/profile/preferred-locale`.\r\nThe subject is resolved from the authenticated principal, never the body.",
"properties": {
"locale": {
"description": "The requested BCP-47 language tag (e.g. `ar-AE`).",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"SetProfileNameRequest": {
"additionalProperties": false,
"description": "Body for `PUT /api/v1/profile/name`. The subject is resolved from the authenticated\r\nprincipal, never the body.",
"properties": {
"firstName": {
"description": "The first name. Required.",
"nullable": true,
"type": "string"
},
"lastName": {
"description": "The last name. Optional.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"SetSupportAgentStatusRequestBody": {
"additionalProperties": false,
"description": "Request body for a bulk agent status change.",
"properties": {
"agentIds": {
"items": {
"format": "uuid",
"type": "string"
},
"nullable": true,
"type": "array"
},
"appId": {
"format": "uuid",
"type": "string"
},
"status": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"SetTrustedEhrIssuerStatusRequest": {
"additionalProperties": false,
"description": "Wire body for changing a trusted issuer's status.",
"properties": {
"reason": {
"description": "Operator-supplied reason, recorded for audit.",
"nullable": true,
"type": "string"
},
"status": {
"description": "One of `Active`, `Suspended`, `Withdrawn`.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"SetUserRoleRequest": {
"additionalProperties": false,
"description": "Request body for M:Essence.Identity.Auth.Api.Controllers.AdminUserRolesController.GrantRole(System.String,Essence.Identity.Auth.Api.Controllers.SetUserRoleRequest,System.Threading.CancellationToken).",
"properties": {
"role": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"SetUserRoleResult": {
"additionalProperties": false,
"properties": {
"roles": {
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
},
"userId": {
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"SetupPostureDto": {
"additionalProperties": false,
"description": "Account setup posture nested in Essence.Identity.Auth.Api.Controllers.SessionMeResponse — what the\r\naccount has configured so the client can render a setup checklist\r\nauthoritatively (password → `POST /auth/password/set`, passkeys, MFA,\r\nrecovery).",
"properties": {
"accountCreatedAt": {
"description": "UTC creation timestamp of the account; null when unresolved.",
"format": "date-time",
"nullable": true,
"type": "string"
},
"hasPassword": {
"description": "True when the account has a client-side password set.",
"type": "boolean"
},
"mfaEnabled": {
"description": "True when a second factor (TOTP/SMS/Email) is enrolled.",
"type": "boolean"
},
"passkeyCount": {
"description": "Number of active WebAuthn/passkey credentials enrolled.",
"format": "int32",
"type": "integer"
},
"recoveryConfigured": {
"description": "True when a recovery-phrase proof is enrolled on this account\r\n(`POST /api/v1/auth/recovery-phrase/enrol`; EPIC 44 D-126 phase 2,\r\nFR-05.082) — i.e. the 24-word phrase can recover the vault after a forgotten\r\npassword. This reflects the recovery PHRASE only. Shamir share configuration\r\n(FR-01.096) is owned by the ShamirRecovery module in a different service and is\r\nnot resolved cross-service here; the client still reads that from\r\n`GET /api/v1/recovery/configuration/{userId}`.",
"type": "boolean"
}
},
"type": "object"
},
"SharedDeviceAttestationVerdictDto": {
"additionalProperties": false,
"description": "The verdict, and the device it names when one was resolved.",
"properties": {
"label": {
"description": "The device's label, when one was resolved.",
"nullable": true,
"type": "string"
},
"outcome": {
"description": "One of the kebab-case verdicts listed on the endpoint.",
"nullable": true,
"type": "string"
},
"revokedAt": {
"description": "When the device was revoked, for a `revoked` verdict.",
"format": "date-time",
"nullable": true,
"type": "string"
},
"sharedDeviceId": {
"description": "The device; present whenever the attestation's key resolved to one.",
"format": "uuid",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"SharedDeviceDto": {
"additionalProperties": false,
"properties": {
"enrolledAt": {
"format": "date-time",
"type": "string"
},
"enrolledByUserId": {
"format": "uuid",
"type": "string"
},
"id": {
"format": "uuid",
"type": "string"
},
"keyRotatedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"keyThumbprint": {
"nullable": true,
"type": "string"
},
"label": {
"nullable": true,
"type": "string"
},
"organizationId": {
"format": "uuid",
"type": "string"
},
"publicKeyJwk": {
"nullable": true,
"type": "string"
},
"revocationReason": {
"nullable": true,
"type": "string"
},
"revokedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"revokedByUserId": {
"format": "uuid",
"nullable": true,
"type": "string"
},
"status": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"SignUpProofOfWork": {
"additionalProperties": false,
"properties": {
"challenge": {
"nullable": true,
"type": "string"
},
"solution": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"SmartTokenExchangeRequest": {
"additionalProperties": false,
"description": "Wire body for the SMART launch-token exchange.",
"properties": {
"clientId": {
"description": "The registered SMART app's client id.",
"nullable": true,
"type": "string"
},
"iss": {
"description": "The EHR's FHIR base URL.",
"nullable": true,
"type": "string"
},
"launchToken": {
"description": "The EHR's one-time opaque launch token.",
"nullable": true,
"type": "string"
},
"requestedScopes": {
"description": "Explicit scope array; takes precedence over Essence.Identity.Auth.Api.Controllers.SmartTokenExchangeRequest.Scope when present.",
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
},
"scope": {
"description": "Space-delimited OAuth scope string (the SMART-native shape).",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"SmartTokenExchangeResponse": {
"additionalProperties": false,
"description": "Contracted success body of the SMART launch-token exchange.",
"properties": {
"accessToken": {
"description": "Scoped FHIR access token, audience-bound to the EHR.",
"nullable": true,
"type": "string"
},
"encounter": {
"description": "Opaque vendor encounter reference (`launch/encounter`), when launched.",
"nullable": true,
"type": "string"
},
"expiresIn": {
"description": "Access-token lifetime in seconds.",
"format": "int32",
"type": "integer"
},
"grantedScopes": {
"description": "The scopes identity was willing to grant.",
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
},
"idToken": {
"description": "Clinician identity token, audience-bound to the SMART app.",
"nullable": true,
"type": "string"
},
"patient": {
"description": "Opaque vendor patient reference (`launch/patient`).",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"SmsEnrolmentResponse": {
"additionalProperties": false,
"description": "Text-message codes are on: the masked number they go to, and the backup codes (shown once).",
"properties": {
"backupCodes": {
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
},
"enrolled": {
"type": "boolean"
},
"maskedNumber": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"SponsoredPremiumInput": {
"additionalProperties": false,
"properties": {
"entitlementLabel": {
"nullable": true,
"type": "string"
},
"planLabel": {
"nullable": true,
"type": "string"
},
"sponsorName": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"StartAccountMergeRequest": {
"additionalProperties": false,
"description": "Wire body to start a merge session.",
"properties": {
"retiredAccountId": {
"description": "The account being retired (folded away).",
"format": "uuid",
"type": "string"
},
"retiringAccountIdentifier": {
"description": "The sign-in address naming the account to retire, when its id is unknown. Opens a\r\n`PendingBinding` session: the address is resolved and bound at `prove`,\r\nafter a second factor enrolled on that account verifies — never at open, so opening\r\na session cannot be used to test whether an address holds an Essence account.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"StartAccountMergeResponse": {
"additionalProperties": false,
"properties": {
"mergeSessionId": {
"format": "uuid",
"type": "string"
},
"status": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"StartKeyClaimRequestBody": {
"additionalProperties": false,
"description": "Request body for starting the key claim.",
"properties": {
"guardianshipId": {
"description": "Optional link to the originating guardianship.",
"format": "uuid",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"StartKeyClaimResult": {
"additionalProperties": false,
"properties": {
"challengeId": {
"format": "uuid",
"type": "string"
},
"claimId": {
"format": "uuid",
"type": "string"
},
"requiredAssurance": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"StepRequest": {
"additionalProperties": false,
"description": "Body for advancing a session to a coarse step.",
"properties": {
"step": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"StepUpAssertionResponse": {
"additionalProperties": false,
"description": "Wire form of the signed irreversible-action step-up assertion (FR-15.008.7).",
"properties": {
"action": {
"nullable": true,
"type": "string"
},
"challengeId": {
"nullable": true,
"type": "string"
},
"factor": {
"nullable": true,
"type": "string"
},
"issuedAtUtc": {
"format": "date-time",
"type": "string"
},
"passwordReverified": {
"type": "boolean"
},
"signature": {
"nullable": true,
"type": "string"
},
"userId": {
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"StepUpEmailCodeRequest": {
"additionalProperties": false,
"description": "Request body for `POST /api/v1/auth/step-up/email-code` (#8753).",
"properties": {
"action": {
"description": "The step-up action the code will elevate for, e.g. `password-change`.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"SubjectExportDelegationRequest": {
"additionalProperties": false,
"description": "Request to mint a subject-export delegation credential for the caller.",
"properties": {
"exportRequestId": {
"description": "The queued export the credential is bound to.",
"format": "uuid",
"type": "string"
},
"lifetimeSeconds": {
"description": "Lifetime the caller's compilation SLA needs. Clamped at mint time to the credential's own\r\nceiling — a caller cannot widen it by asking.",
"format": "int32",
"type": "integer"
}
},
"type": "object"
},
"SubjectExportDelegationResponse": {
"additionalProperties": false,
"description": "A minted subject-export delegation credential.",
"properties": {
"expiresAt": {
"description": "Absolute UTC expiry.",
"format": "date-time",
"type": "string"
},
"token": {
"description": "The signed JWT to present to subject-export source endpoints.",
"nullable": true,
"type": "string"
},
"tokenId": {
"description": "Its `jti`, for audit correlation.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"SubjectNameabilityDto": {
"additionalProperties": false,
"properties": {
"exists": {
"type": "boolean"
},
"hasRecordedName": {
"type": "boolean"
},
"userId": {
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"SubmitAppealByTokenRequest": {
"additionalProperties": false,
"description": "Body for `POST /api/v1/account/appeals/by-token` — the sessionless appeal.",
"properties": {
"statement": {
"description": "The appellant's statement.",
"nullable": true,
"type": "string"
},
"token": {
"description": "The single-purpose notice token issued at the sign-in refusal.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"SubmitAppealRequest": {
"additionalProperties": false,
"description": "Body for `POST /api/v1/account/appeals` (the appellant's statement).",
"properties": {
"actionId": {
"description": "The account-action decision being appealed.",
"format": "uuid",
"type": "string"
},
"statement": {
"description": "The appellant's statement.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"SubmitCustodialOrderRequest": {
"additionalProperties": false,
"description": "Submission body. Matches the shipped client's `submitOrderProof` payload.",
"properties": {
"childUserId": {
"description": "The child's existing subject id, when custody is being taken of an existing record.",
"format": "uuid",
"nullable": true,
"type": "string"
},
"documentName": {
"nullable": true,
"type": "string"
},
"documentRef": {
"description": "Opaque reference to the client-encrypted order document, when stored.",
"nullable": true,
"type": "string"
},
"effectiveDate": {
"description": "ISO-8601 date the order took effect.",
"nullable": true,
"type": "string"
},
"evidenceCodes": {
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
},
"instrumentCode": {
"nullable": true,
"type": "string"
},
"issuingAuthority": {
"nullable": true,
"type": "string"
},
"jurisdictionCode": {
"nullable": true,
"type": "string"
},
"orderReference": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"SupportAccessCustomerDecisionDto": {
"additionalProperties": false,
"properties": {
"consentId": {
"format": "uuid",
"type": "string"
},
"decidedAt": {
"format": "date-time",
"type": "string"
},
"expiresAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"grantId": {
"format": "uuid",
"nullable": true,
"type": "string"
},
"requestId": {
"format": "uuid",
"type": "string"
},
"status": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"SupportAccessDecisionBody": {
"additionalProperties": false,
"description": "The customer's decision — the body\r\n`essence-web/src/features/support-access/api/supportAccessApi.ts` already posts.",
"properties": {
"decision": {
"description": "`allow` or `deny`.",
"nullable": true,
"type": "string"
},
"grantId": {
"description": "The grant the caller's own client created, when it did. Verified, not trusted.",
"format": "uuid",
"nullable": true,
"type": "string"
},
"reason": {
"description": "The customer's own words when denying. Never required.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"SupportAccessRequestDto": {
"additionalProperties": false,
"properties": {
"agentId": {
"format": "uuid",
"type": "string"
},
"durationMinutes": {
"format": "int32",
"type": "integer"
},
"partnerAppId": {
"format": "uuid",
"type": "string"
},
"raisedAt": {
"format": "date-time",
"type": "string"
},
"requestId": {
"format": "uuid",
"type": "string"
},
"scopes": {
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
},
"status": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"SupportAccessRequestListItemDto": {
"additionalProperties": false,
"properties": {
"agentId": {
"format": "uuid",
"type": "string"
},
"agentPrincipalId": {
"format": "uuid",
"type": "string"
},
"consentId": {
"format": "uuid",
"nullable": true,
"type": "string"
},
"decidedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"declineReasonCode": {
"nullable": true,
"type": "string"
},
"durationMinutes": {
"format": "int32",
"type": "integer"
},
"grantId": {
"format": "uuid",
"nullable": true,
"type": "string"
},
"partnerAppId": {
"format": "uuid",
"type": "string"
},
"raisedAt": {
"format": "date-time",
"type": "string"
},
"raisedByUserId": {
"format": "uuid",
"type": "string"
},
"reasonCode": {
"nullable": true,
"type": "string"
},
"requestId": {
"format": "uuid",
"type": "string"
},
"scopes": {
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
},
"status": {
"nullable": true,
"type": "string"
},
"subjectUserReference": {
"nullable": true,
"type": "string"
},
"supervisorAgentId": {
"format": "uuid",
"nullable": true,
"type": "string"
},
"supervisorDecidedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"supervisorPrincipalId": {
"format": "uuid",
"nullable": true,
"type": "string"
},
"ticketReference": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"SupportAccessRequestListItemDtoCursorResult": {
"additionalProperties": false,
"properties": {
"hasMore": {
"type": "boolean"
},
"items": {
"items": {
"$ref": "#/components/schemas/SupportAccessRequestListItemDto"
},
"nullable": true,
"type": "array"
},
"nextCursor": {
"nullable": true,
"type": "string"
},
"pageSize": {
"format": "int32",
"type": "integer"
},
"previousCursor": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"SupportAccessSessionDescriptorDto": {
"additionalProperties": false,
"properties": {
"agentDisplayName": {
"nullable": true,
"type": "string"
},
"agentPrincipalId": {
"format": "uuid",
"type": "string"
},
"consentId": {
"format": "uuid",
"type": "string"
},
"partnerAppId": {
"format": "uuid",
"type": "string"
},
"partnerName": {
"nullable": true,
"type": "string"
},
"partnerNameStatus": {
"nullable": true,
"type": "string"
},
"publisherName": {
"nullable": true,
"type": "string"
},
"publisherVerified": {
"nullable": true,
"type": "boolean"
},
"reasonCode": {
"nullable": true,
"type": "string"
},
"ticketReference": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"SupportAgentDto": {
"additionalProperties": false,
"properties": {
"agentId": {
"format": "uuid",
"type": "string"
},
"displayName": {
"nullable": true,
"type": "string"
},
"email": {
"nullable": true,
"type": "string"
},
"enrolledAt": {
"format": "date-time",
"type": "string"
},
"principalId": {
"format": "uuid",
"nullable": true,
"type": "string"
},
"role": {
"nullable": true,
"type": "string"
},
"status": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"SupportAgentInvitationDto": {
"additionalProperties": false,
"properties": {
"acceptedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"agentId": {
"format": "uuid",
"type": "string"
},
"displayName": {
"nullable": true,
"type": "string"
},
"email": {
"nullable": true,
"type": "string"
},
"invitedAt": {
"format": "date-time",
"type": "string"
},
"partnerAppId": {
"format": "uuid",
"type": "string"
},
"partnerAppName": {
"nullable": true,
"type": "string"
},
"partnerNameStatus": {
"nullable": true,
"type": "string"
},
"publisherName": {
"nullable": true,
"type": "string"
},
"publisherVerified": {
"nullable": true,
"type": "boolean"
},
"role": {
"nullable": true,
"type": "string"
},
"status": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"SupportAgentStatusChangeDto": {
"additionalProperties": false,
"properties": {
"updated": {
"format": "int32",
"type": "integer"
}
},
"type": "object"
},
"SupportImpersonationPolicyDto": {
"additionalProperties": false,
"properties": {
"allowedScopes": {
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
},
"appId": {
"format": "uuid",
"type": "string"
},
"configured": {
"type": "boolean"
},
"dailyRequestLimitPerAgent": {
"format": "int32",
"type": "integer"
},
"dualApprovalRequired": {
"type": "boolean"
},
"eligibleRoles": {
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
},
"maxDurationMinutes": {
"format": "int32",
"type": "integer"
},
"reasonCodes": {
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
},
"updatedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"SupportImpersonationPolicyRequestBody": {
"additionalProperties": false,
"description": "Request body for saving a support-impersonation policy (the dashboard's `ImpersonationPolicy`).",
"properties": {
"allowedScopes": {
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
},
"appId": {
"format": "uuid",
"type": "string"
},
"dailyRequestLimitPerAgent": {
"format": "int32",
"type": "integer"
},
"dualApprovalRequired": {
"type": "boolean"
},
"eligibleRoles": {
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
},
"maxDurationMinutes": {
"format": "int32",
"type": "integer"
},
"reasonCodes": {
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
}
},
"type": "object"
},
"SuspendDelegatedAgentRequest": {
"additionalProperties": false,
"description": "Request body for incident-driven suspension.",
"properties": {
"incidentId": {
"description": "The EPIC 12 incident driving containment.",
"format": "uuid",
"type": "string"
},
"reason": {
"description": "A closed-vocabulary suspension reason.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"SuspendDelegatedAgentResponse": {
"additionalProperties": false,
"description": "Suspension response — the EPIC 9 containment leg's return value.",
"properties": {
"sessionsRevoked": {
"description": "How many live sessions were cut.",
"format": "int32",
"type": "integer"
},
"suspensionReference": {
"description": "The reference the containment chain records.",
"nullable": true,
"type": "string"
},
"wasAlreadySuspended": {
"description": "True when the agent's access had already been cut.",
"type": "boolean"
}
},
"type": "object"
},
"TakeoverIncidentView": {
"additionalProperties": false,
"properties": {
"incidentId": {
"format": "uuid",
"type": "string"
},
"keysRotatedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"openedAt": {
"format": "date-time",
"type": "string"
},
"sessionsTerminated": {
"format": "int32",
"type": "integer"
},
"sharesRevokedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"sharesRevokedCount": {
"format": "int32",
"type": "integer"
}
},
"type": "object"
},
"TakeoverStateView": {
"additionalProperties": false,
"properties": {
"frozen": {
"type": "boolean"
},
"frozenAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"incident": {
"$ref": "#/components/schemas/TakeoverIncidentView"
}
},
"type": "object"
},
"TerminatePrincipalAccessRequest": {
"additionalProperties": false,
"description": "Request body for an FR-09.044 administrative access termination. The acting operator is\r\ndeliberately absent — it comes from the caller's token.",
"properties": {
"campaignRef": {
"description": "The recertification campaign this termination is anchored to. Required.",
"nullable": true,
"type": "string"
},
"deviceId": {
"description": "Required when Essence.Identity.Auth.Api.Controllers.TerminatePrincipalAccessRequest.Scope is `device`.",
"format": "uuid",
"nullable": true,
"type": "string"
},
"grantId": {
"description": "The access grant being revoked, if the campaign named one.",
"format": "uuid",
"nullable": true,
"type": "string"
},
"reason": {
"description": "Non-PII reason token (e.g. `recertification-deadline-unattested`). Required.",
"nullable": true,
"type": "string"
},
"scope": {
"description": "`all` (default), `device`, or `sessions`.",
"nullable": true,
"type": "string"
},
"sessionIds": {
"description": "Required when Essence.Identity.Auth.Api.Controllers.TerminatePrincipalAccessRequest.Scope is `sessions`.",
"items": {
"format": "uuid",
"type": "string"
},
"nullable": true,
"type": "array"
},
"subjectUserId": {
"description": "The staff principal whose access is being terminated.",
"format": "uuid",
"type": "string"
},
"systemCode": {
"description": "The EPIC 87 access-bearing system code the revocation is on behalf of, if named.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"TerminatePrincipalAccessResult": {
"additionalProperties": false,
"properties": {
"credentialsRevoked": {
"format": "int32",
"type": "integer"
},
"recordId": {
"format": "uuid",
"nullable": true,
"type": "string"
},
"refusedReason": {
"nullable": true,
"type": "string"
},
"sessionsRevoked": {
"format": "int32",
"type": "integer"
},
"terminated": {
"type": "boolean"
},
"terminatedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"TerminateSupportAccessSessionRequestBody": {
"additionalProperties": false,
"description": "Request body for a partner force-terminate.",
"properties": {
"reason": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"TerminateSupportAccessSessionResult": {
"additionalProperties": false,
"properties": {
"alreadyEnded": {
"type": "boolean"
},
"sessionId": {
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"TokenValidationDto": {
"additionalProperties": false,
"properties": {
"deviceId": {
"format": "uuid",
"nullable": true,
"type": "string"
},
"email": {
"nullable": true,
"type": "string"
},
"emailVerified": {
"type": "boolean"
},
"errorMessage": {
"nullable": true,
"type": "string"
},
"isValid": {
"type": "boolean"
},
"mfaEnabled": {
"type": "boolean"
},
"userId": {
"format": "uuid",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"TransitionAuditResultDto": {
"additionalProperties": false,
"properties": {
"auditRecordId": {
"nullable": true,
"type": "string"
},
"recordedAtIso": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"TransitionGuardianshipRequest": {
"additionalProperties": false,
"description": "Request body for committing the majority transition.",
"properties": {
"reConsentDecisions": {
"description": "The young adult's per-grant re-consent decisions from the affirmative gate.",
"items": {
"$ref": "#/components/schemas/ReConsentChoiceDto"
},
"nullable": true,
"type": "array"
}
},
"type": "object"
},
"TrustDeviceResult": {
"additionalProperties": false,
"properties": {
"message": {
"nullable": true,
"type": "string"
},
"success": {
"type": "boolean"
}
},
"type": "object"
},
"TrustedEhrIssuerDto": {
"additionalProperties": false,
"properties": {
"allowedClientIds": {
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
},
"displayName": {
"nullable": true,
"type": "string"
},
"distrustReason": {
"nullable": true,
"type": "string"
},
"distrustedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"grantableScopes": {
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
},
"id": {
"format": "uuid",
"type": "string"
},
"iss": {
"nullable": true,
"type": "string"
},
"organizationId": {
"format": "uuid",
"nullable": true,
"type": "string"
},
"status": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"UaePassAccountLinkRequest": {
"additionalProperties": false,
"description": "Body of `POST auth/federated-accounts/uae-pass`.",
"properties": {
"homeRegion": {
"description": "The sovereign region a new account is homed in (the caller's, `AE`).",
"nullable": true,
"type": "string"
},
"subject": {
"description": "The verified UAE Pass `sub`.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"UaePassAccountLinkResponse": {
"additionalProperties": false,
"description": "Response of `POST auth/federated-accounts/uae-pass`.",
"properties": {
"isNewUser": {
"description": "True when this call provisioned the account.",
"type": "boolean"
},
"userId": {
"description": "The Essence user id the subject is linked to.",
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"UndoAccountMergeResponse": {
"additionalProperties": false,
"properties": {
"mergeSessionId": {
"format": "uuid",
"type": "string"
},
"reversedAt": {
"format": "date-time",
"type": "string"
},
"status": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"UnlockAccountResult": {
"additionalProperties": false,
"properties": {
"message": {
"nullable": true,
"type": "string"
},
"success": {
"type": "boolean"
},
"userNotFound": {
"type": "boolean"
}
},
"type": "object"
},
"UpdateDeviceNameRequest": {
"additionalProperties": false,
"properties": {
"friendlyName": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"UpdateDeviceNameResult": {
"additionalProperties": false,
"properties": {
"message": {
"nullable": true,
"type": "string"
},
"success": {
"type": "boolean"
}
},
"type": "object"
},
"UserIdentityAttributesDto": {
"additionalProperties": false,
"properties": {
"email": {
"nullable": true,
"type": "string"
},
"emailVerified": {
"type": "boolean"
},
"exists": {
"type": "boolean"
},
"firstName": {
"nullable": true,
"type": "string"
},
"lastName": {
"nullable": true,
"type": "string"
},
"nameAssured": {
"type": "boolean"
},
"phone": {
"nullable": true,
"type": "string"
},
"phoneVerified": {
"type": "boolean"
},
"userId": {
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"ValidateTokenQuery": {
"additionalProperties": false,
"properties": {
"accessToken": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"VaultScopeInput": {
"additionalProperties": false,
"properties": {
"access": {
"nullable": true,
"type": "string"
},
"description": {
"nullable": true,
"type": "string"
},
"vaultLabel": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"VerificationActionResult": {
"additionalProperties": false,
"properties": {
"applied": {
"format": "int32",
"type": "integer"
},
"appliedVerificationIds": {
"items": {
"format": "uuid",
"type": "string"
},
"nullable": true,
"type": "array"
},
"requested": {
"format": "int32",
"type": "integer"
}
},
"type": "object"
},
"VerificationIdsRequest": {
"additionalProperties": false,
"description": "Request body carrying the target verification ids for a bulk recheck / reminder.",
"properties": {
"verificationIds": {
"items": {
"format": "uuid",
"type": "string"
},
"nullable": true,
"type": "array"
}
},
"type": "object"
},
"VerifiedNameChangeView": {
"additionalProperties": false,
"properties": {
"accountId": {
"format": "uuid",
"type": "string"
},
"affectedConsentRefs": {
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
},
"auditAnchorRef": {
"nullable": true,
"type": "string"
},
"cancelledAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"changeId": {
"format": "uuid",
"type": "string"
},
"committedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"deedPollDocumentId": {
"format": "uuid",
"nullable": true,
"type": "string"
},
"newNameHash": {
"nullable": true,
"type": "string"
},
"newNameMasked": {
"nullable": true,
"type": "string"
},
"notifiedCount": {
"format": "int32",
"type": "integer"
},
"previousNameDisposition": {
"nullable": true,
"type": "string"
},
"previousNameHash": {
"nullable": true,
"type": "string"
},
"previousNameMasked": {
"nullable": true,
"type": "string"
},
"reattestationRef": {
"nullable": true,
"type": "string"
},
"reattestedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"status": {
"nullable": true,
"type": "string"
},
"syncedConnectionRefs": {
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
},
"withheldCount": {
"format": "int32",
"type": "integer"
}
},
"type": "object"
},
"VerifyEmailOtpByEmailRequest": {
"additionalProperties": false,
"description": "Request body for `POST /email/verify-otp/by-email` (#7539) — the sessionless\r\nredemption. Carries the address because an anonymous caller has nothing else to identify\r\nitself with.",
"properties": {
"code": {
"description": "The 6-digit code from the verification email.",
"nullable": true,
"type": "string"
},
"email": {
"description": "The address the account was registered with.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"VerifyEmailOtpByEmailResponse": {
"additionalProperties": false,
"description": "Response body for a successful `POST /email/verify-otp/by-email`.",
"properties": {
"verified": {
"description": "Always true when this body is returned.",
"type": "boolean"
}
},
"type": "object"
},
"VerifyEmailOtpRequest": {
"additionalProperties": false,
"description": "Request body for `POST /email/verify-otp` — the in-app email-verification\r\nOTP the user typed into the app.",
"properties": {
"code": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"VerifyEmailOtpResult": {
"additionalProperties": false,
"properties": {
"accessToken": {
"nullable": true,
"type": "string"
},
"accessTokenExpiresAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"attemptsExhausted": {
"type": "boolean"
},
"codeExpired": {
"type": "boolean"
},
"message": {
"nullable": true,
"type": "string"
},
"refreshToken": {
"nullable": true,
"type": "string"
},
"refreshTokenExpiresAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"verified": {
"type": "boolean"
}
},
"type": "object"
},
"VerifyEmailResult": {
"additionalProperties": false,
"properties": {
"userId": {
"format": "uuid",
"nullable": true,
"type": "string"
},
"verified": {
"type": "boolean"
}
},
"type": "object"
},
"VerifyExecutorOfficerRequest": {
"additionalProperties": false,
"description": "Request body for recording an officer's identity verification.",
"properties": {
"verificationLevel": {
"description": "The assurance level reached (e.g. `medium`, `high`).",
"nullable": true,
"type": "string"
},
"verificationReference": {
"description": "Non-PII reference to the identity-assurance record that verified the officer.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"VerifyKeyClaimRequestBody": {
"additionalProperties": false,
"description": "Request body for verifying the key claim.",
"properties": {
"code": {
"description": "The one-time code the subject received.",
"nullable": true,
"type": "string"
},
"rewrappedVaultKeyEnvelope": {
"description": "The device-produced re-wrapped vault UMK envelope (private half never leaves the device).",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"VerifyKeyClaimResult": {
"additionalProperties": false,
"properties": {
"claimId": {
"format": "uuid",
"type": "string"
},
"identityChangeRef": {
"nullable": true,
"type": "string"
},
"remainingAttempts": {
"format": "int32",
"type": "integer"
},
"revocationProofRef": {
"nullable": true,
"type": "string"
},
"verified": {
"type": "boolean"
},
"verifiedAtIso": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"VerifyMfaCommand": {
"additionalProperties": false,
"properties": {
"allowWhenMfaDisabled": {
"type": "boolean"
},
"code": {
"nullable": true,
"type": "string"
},
"method": {
"$ref": "#/components/schemas/MfaMethod"
},
"userId": {
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"VerifyMfaResult": {
"additionalProperties": false,
"properties": {
"isValid": {
"type": "boolean"
},
"message": {
"nullable": true,
"type": "string"
},
"success": {
"type": "boolean"
}
},
"type": "object"
},
"VerifyNewPrimaryContactAddressRequest": {
"additionalProperties": false,
"description": "Wire body to verify the new address.",
"properties": {
"code": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"VerifyNewPrimaryContactAddressResult": {
"additionalProperties": false,
"properties": {
"changeId": {
"format": "uuid",
"type": "string"
},
"status": {
"nullable": true,
"type": "string"
},
"trustWindowClosesAt": {
"format": "date-time",
"type": "string"
}
},
"type": "object"
},
"VerifyProfessionalAdviserRequest": {
"additionalProperties": false,
"description": "Request body for recording an adviser's identity verification.",
"properties": {
"verificationLevel": {
"description": "The assurance level reached, e.g. `high`.",
"nullable": true,
"type": "string"
},
"verificationReference": {
"description": "Non-PII reference to the identity-assurance record.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"VerifySafeguardingOfficerRequest": {
"additionalProperties": false,
"description": "Request body for recording an officer's identity verification.",
"properties": {
"verificationLevel": {
"description": "The assurance level reached, e.g. `high`.",
"nullable": true,
"type": "string"
},
"verificationReference": {
"description": "Non-PII reference to the identity-assurance record.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"VerifySharedDeviceAttestationRequest": {
"additionalProperties": false,
"description": "The check's input. Organisation, user and session come from the worker's token.",
"properties": {
"attestation": {
"nullable": true,
"type": "string"
},
"organizationId": {
"format": "uuid",
"type": "string"
},
"sessionId": {
"format": "uuid",
"type": "string"
},
"userId": {
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"WebAuthnAuthenticationOptions": {
"additionalProperties": false,
"properties": {
"allowCredentials": {
"items": {
"$ref": "#/components/schemas/WebAuthnCredentialDescriptor"
},
"nullable": true,
"type": "array"
},
"challenge": {
"nullable": true,
"type": "string"
},
"rpId": {
"nullable": true,
"type": "string"
},
"sessionId": {
"nullable": true,
"type": "string"
},
"timeout": {
"format": "int32",
"type": "integer"
},
"userVerification": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"WebAuthnAuthenticationResult": {
"additionalProperties": false,
"properties": {
"accessToken": {
"nullable": true,
"type": "string"
},
"deviceLimit": {
"$ref": "#/components/schemas/DeviceLimitPause"
},
"deviceLimitReached": {
"type": "boolean"
},
"errorMessage": {
"nullable": true,
"type": "string"
},
"expiresIn": {
"format": "int32",
"type": "integer"
},
"mfaRequired": {
"type": "boolean"
},
"refreshToken": {
"nullable": true,
"type": "string"
},
"success": {
"type": "boolean"
},
"userId": {
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"WebAuthnAuthenticatorSelection": {
"additionalProperties": false,
"properties": {
"authenticatorAttachment": {
"nullable": true,
"type": "string"
},
"requireResidentKey": {
"type": "boolean"
},
"residentKey": {
"nullable": true,
"type": "string"
},
"userVerification": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"WebAuthnCredentialDescriptor": {
"additionalProperties": false,
"properties": {
"id": {
"nullable": true,
"type": "string"
},
"transports": {
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
},
"type": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"WebAuthnCredentialListResponse": {
"additionalProperties": false,
"description": "Envelope for the passkey list, matching the client's `{ data: [...] }` shape.",
"properties": {
"data": {
"items": {
"$ref": "#/components/schemas/WebAuthnCredentialSummary"
},
"nullable": true,
"type": "array"
}
},
"type": "object"
},
"WebAuthnCredentialSummary": {
"additionalProperties": false,
"properties": {
"aaguid": {
"nullable": true,
"type": "string"
},
"authenticatorModel": {
"nullable": true,
"type": "string"
},
"certification": {
"nullable": true,
"type": "string"
},
"certificationWithdrawnReason": {
"nullable": true,
"type": "string"
},
"createdAt": {
"format": "date-time",
"type": "string"
},
"id": {
"nullable": true,
"type": "string"
},
"lastUsed": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"name": {
"nullable": true,
"type": "string"
},
"transports": {
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
},
"type": {
"nullable": true,
"type": "string"
},
"webAuthnCredentialId": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"WebAuthnPubKeyCredParam": {
"additionalProperties": false,
"properties": {
"alg": {
"format": "int32",
"type": "integer"
},
"type": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"WebAuthnRegistrationOptions": {
"additionalProperties": false,
"properties": {
"attestation": {
"nullable": true,
"type": "string"
},
"authenticatorSelection": {
"$ref": "#/components/schemas/WebAuthnAuthenticatorSelection"
},
"challenge": {
"nullable": true,
"type": "string"
},
"excludeCredentials": {
"items": {
"$ref": "#/components/schemas/WebAuthnCredentialDescriptor"
},
"nullable": true,
"type": "array"
},
"pubKeyCredParams": {
"items": {
"$ref": "#/components/schemas/WebAuthnPubKeyCredParam"
},
"nullable": true,
"type": "array"
},
"relyingParty": {
"$ref": "#/components/schemas/WebAuthnRelyingParty"
},
"sessionId": {
"nullable": true,
"type": "string"
},
"timeout": {
"format": "int32",
"type": "integer"
},
"user": {
"$ref": "#/components/schemas/WebAuthnUserEntity"
}
},
"type": "object"
},
"WebAuthnRegistrationResult": {
"additionalProperties": false,
"properties": {
"createdAt": {
"format": "date-time",
"type": "string"
},
"credentialId": {
"format": "uuid",
"type": "string"
},
"credentialType": {
"nullable": true,
"type": "string"
},
"deviceName": {
"nullable": true,
"type": "string"
},
"errorMessage": {
"nullable": true,
"type": "string"
},
"success": {
"type": "boolean"
},
"vaultBindingToken": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"WebAuthnRelyingParty": {
"additionalProperties": false,
"properties": {
"id": {
"nullable": true,
"type": "string"
},
"name": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"WebAuthnUserEntity": {
"additionalProperties": false,
"properties": {
"displayName": {
"nullable": true,
"type": "string"
},
"id": {
"nullable": true,
"type": "string"
},
"name": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"WithdrawAccountMergeApprovalResponse": {
"additionalProperties": false,
"description": "The result of retracting a queued approval request (gap G-withdraw,\r\n`uxf-2026-08-12-017`): the merge session and the approval state the SERVER now\r\nholds. Exactly the two fields the member's client reads before releasing its override —\r\nit branches on this outcome rather than on anything it stored locally.",
"properties": {
"approvalStatus": {
"nullable": true,
"type": "string"
},
"mergeSessionId": {
"format": "uuid",
"type": "string"
}
},
"type": "object"
}
},
"securitySchemes": {
"Bearer": {
"bearerFormat": "JWT",
"description": "JWT Authorization header using the Bearer scheme. Enter 'Bearer' [space] and then your token.",
"scheme": "bearer",
"type": "http"
}
}
},
"info": {
"contact": {
"email": "api@essence.digital",
"name": "Essence Platform Team"
},
"description": "API for user authentication, registration, and session management.\n\n## Features\n- User registration with email/password\n- Multi-factor authentication (TOTP, SMS, Email)\n- Device fingerprinting and trust management\n- JWT tokens with RS256 signing\n- Refresh token rotation\n- Federated identity (UAE PASS, Azure AD, Okta, etc.)\n\n## Security\n- Zero-knowledge architecture (client-side password hashing)\n- Account lockout policy (5 attempts = 30min)\n- Token blacklisting for revocation\n- Constant-time password verification (SEC-005)\n- Adopted Essence platform foundation (Phase 1 WS-B)",
"title": "Essence Authentication Service API",
"version": "v1.0"
},
"openapi": "3.0.1",
"paths": {
"/.well-known/jwks.json": {
"get": {
"parameters": [
{
"in": "header",
"name": "X-Api-Version",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/JwksDocument"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/JwksDocument"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/JwksDocument"
}
}
},
"description": "OK"
},
"503": {
"description": "Service Unavailable"
}
},
"summary": "Get JSON Web Key Set (JWKS) for token validation.\r\nThis endpoint is called by OAuth clients and resource servers to validate JWT tokens.",
"tags": [
"Jwks"
]
}
},
"/.well-known/openid-configuration": {
"get": {
"parameters": [
{
"in": "header",
"name": "X-Api-Version",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OpenIdConfiguration"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/OpenIdConfiguration"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/OpenIdConfiguration"
}
}
},
"description": "OK"
}
},
"summary": "Get OpenID Connect discovery document.",
"tags": [
"Jwks"
]
}
},
"/api/v1/access-recertification/terminations": {
"post": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/TerminatePrincipalAccessRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/TerminatePrincipalAccessRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/TerminatePrincipalAccessRequest"
}
}
},
"description": "Subject, scope, campaign anchor and reason."
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TerminatePrincipalAccessResult"
}
}
},
"description": "Executed. A principal who was already signed out yields `sessionsRevoked: 0` — that is\r\na successful termination of nothing, not a failure, and it is still recorded as evidence."
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The request is not accountable (missing actor, campaign, reason or scope target)."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The caller does not hold the access-recertification-operator role."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TerminatePrincipalAccessResult"
}
}
},
"description": "The subject is unknown or is not a staff principal; nothing was terminated."
}
},
"summary": "Terminates a named staff principal's sessions and issued credentials under the authority of\r\na recertification campaign.",
"tags": [
"AccessRecertificationTermination"
]
}
},
"/api/v1/account/action-notice": {
"get": {
"parameters": [
{
"in": "query",
"name": "case",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AccountActionNoticeDto"
}
}
},
"description": "The current notice."
},
"204": {
"description": "No action is in force on the account."
}
},
"summary": "Returns the honest account-action notice for the signed-in / affected account.\r\nWhen a `case` reference is supplied it scopes the lookup to that decision.\r\nReturns 204 when there is no action on the account.",
"tags": [
"AccountAction"
]
}
},
"/api/v1/account/action-notice/by-token": {
"get": {
"parameters": [
{
"in": "query",
"name": "token",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AccountActionNoticeDto"
}
}
},
"description": "The notice for the token holder."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unknown, expired or already-replaced token."
}
},
"summary": "Returns the account-action notice for the holder of a single-purpose notice\r\ntoken, WITHOUT a session.\r\n\n\r\nA suspended account cannot hold a session, so the person the notice is about\r\nwould otherwise be the one person unable to read it — including the appeal\r\nroute it describes. The token is minted only when that person successfully\r\nproves their password at sign-in, is 256 bits of CSPRNG output, is stored\r\nonly as a hash, expires in 30 minutes, and is accepted by this endpoint\r\nalone. It is deliberately not a bearer token: it can authenticate nothing\r\nelse.\r\n\n\r\nThe appeal case reference is NOT usable for this purpose — it carries ~32\r\nbits behind a guessable date prefix and does not exist until an appeal has\r\nalready been opened.\r\n",
"tags": [
"AccountAction"
]
}
},
"/api/v1/account/actions": {
"post": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/ApplyAccountActionRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApplyAccountActionRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ApplyAccountActionRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApplyAccountActionResult"
}
}
},
"description": "The action was applied."
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid action token or missing required fields."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The target user does not exist."
}
},
"summary": "Applies a graduated administrative action to an end-user account (the EPIC 48\r\nmoderation decision). Admin-only. Emits the shared account-action event.",
"tags": [
"AccountAction"
]
}
},
"/api/v1/account/appeals": {
"post": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/SubmitAppealRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/SubmitAppealRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/SubmitAppealRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AppealCaseDto"
}
}
},
"description": "The appeal was opened."
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The action is not appealable or an appeal already exists."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No such action for this account."
}
},
"summary": "Submits an appeal against an account action on behalf of the affected user.\r\nReturns a returnable case reference + the response-SLA window.",
"tags": [
"AccountAction"
]
}
},
"/api/v1/account/appeals/by-token": {
"get": {
"parameters": [
{
"in": "query",
"name": "token",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AppealCaseDto"
}
}
},
"description": "The appeal case."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unknown/expired token, or no appeal has been opened yet."
}
},
"summary": "Re-reads the appeal opened against the token's action, WITHOUT a session, so a suspended\r\nholder can return and track it.",
"tags": [
"AccountAction"
]
},
"post": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/SubmitAppealByTokenRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/SubmitAppealByTokenRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/SubmitAppealByTokenRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AppealCaseDto"
}
}
},
"description": "The appeal was opened (or already existed)."
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The action is not appealable."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unknown, expired or already-replaced token."
}
},
"summary": "Submits an appeal using the single-purpose notice token, WITHOUT a session — the only\r\nroute available to a suspended holder.\r\n\n\r\nThe notice this token was minted for tells its holder they may appeal. The\r\nsession-based `POST appeals` above resolves the appellant from JWT claims, so until\r\nthis existed the right to appeal was announced to exactly the people who could not\r\nexercise it. The appealed decision is resolved FROM the token — it is not accepted in\r\nthe body — so the token can only ever open an appeal against its own action.\r\n",
"tags": [
"AccountAction"
]
}
},
"/api/v1/account/appeals/{caseRef}": {
"get": {
"parameters": [
{
"in": "path",
"name": "caseRef",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AppealCaseDto"
}
}
},
"description": "The appeal case."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No such appeal for this account."
}
},
"summary": "Re-fetches an appeal's status by case reference.",
"tags": [
"AccountAction"
]
}
},
"/api/v1/account/merge/sessions": {
"post": {
"description": "The surviving account is taken from the validated token, never the body. A\r\n self-service merge always folds another account into the caller's own, so accepting a\r\n client-supplied survivor would be an account-takeover primitive (name a victim as the\r\n retiring account, yourself as the survivor). Any `survivingAccountId` in the body\r\n is ignored; the domain re-asserts the same invariant so this cannot be bypassed.",
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/StartAccountMergeRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/StartAccountMergeRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/StartAccountMergeRequest"
}
}
}
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StartAccountMergeResponse"
}
}
},
"description": "Created"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden"
},
"503": {
"description": "Service Unavailable"
}
},
"summary": "Start a merge session naming the account to retire into the caller's own.",
"tags": [
"AccountMerge"
]
}
},
"/api/v1/account/merge/sessions/{id}/commit": {
"post": {
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/CommitAccountMergeRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/CommitAccountMergeRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/CommitAccountMergeRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CommitAccountMergeResponse"
}
}
},
"description": "OK"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Conflict"
},
"503": {
"description": "Service Unavailable"
}
},
"summary": "Commit the merge (retire + fold). Requires the session to be proven AND a\r\nfresh survivor step-up (WCAG 2.2 SC 3.3.4 error-prevention gate,\r\ndebt-2026-07-03-226). Rejects the destructive confirm with 403 when the\r\nstep-up is absent or invalid.",
"tags": [
"AccountMerge"
]
}
},
"/api/v1/account/merge/sessions/{id}/prove": {
"post": {
"description": "The body carries the account being proven PLUS a second-factor proof enrolled on\r\nTHAT account. The caller's own authenticated session is not evidence about the\r\nretiring account — which is, by construction, not the account they are signed in as —\r\nso the factor is verified against `accountId`, never against the caller.",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/ProveAccountMergeRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProveAccountMergeRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProveAccountMergeRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProveAccountMergeResponse"
}
}
},
"description": "OK"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Conflict"
}
},
"summary": "Bind proof-of-control for one account of the session. Submit once per\r\naccount; the session becomes `Proven` once both are bound.",
"tags": [
"AccountMerge"
]
}
},
"/api/v1/account/merge/sessions/{id}/status": {
"get": {
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AccountMergeStatusResult"
}
}
},
"description": "OK"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
}
},
"summary": "Read the merge session's per-stage progress so the UI can render honest,\r\ndiscrete \"visibly working\" stages (rekey → move_records → unify_identity →\r\nrepoint_consents) instead of an indeterminate busy state\r\n(debt-2026-07-03-226). Only the session initiator may read it.",
"tags": [
"AccountMerge"
]
}
},
"/api/v1/account/merge/sessions/{id}/undo": {
"post": {
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UndoAccountMergeResponse"
}
}
},
"description": "OK"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Conflict"
}
},
"summary": "Reverse a committed merge within the grace window.",
"tags": [
"AccountMerge"
]
}
},
"/api/v1/account/merge/{id}/policy": {
"get": {
"description": "\n\r\n The same resolver backs the server-side commit gate, so what the member is shown\r\n and what the server enforces cannot diverge. An ungoverned (personal) merge — the\r\n common case — resolves to `allow` with no organisation.\r\n \r\n\n\r\n Only the session initiator may read it: a merge session id would otherwise be an\r\n IDOR handle onto another member's organisation membership.\r\n \r\n\nZero-knowledge: a mode and an organisation display name only — never org data.",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AccountMergeGovernanceResult"
}
}
},
"description": "OK"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
}
},
"summary": "Resolve the organisation governance policy that governs THIS merge — the\r\nmember-facing read behind the step-6 confirm gate (journey\r\n`account-merge-consolidate-duplicate-identities`, debt-2026-07-09-253).\r\nReturns the governing mode (`allow` | `require-approval` | `block`)\r\nand, when an organisation governs it, that organisation's display name.",
"tags": [
"AccountMerge"
]
}
},
"/api/v1/account/merge/{id}/request-approval": {
"post": {
"description": "Calling this is not what makes the org gate apply. The commit gate resolves the\r\ngoverning organisation's policy directly, so a client that never calls this endpoint\r\nstill cannot commit a merge a `require-approval` organisation governs. This\r\nendpoint is how the member puts their merge INTO that org's queue.",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/RequestAccountMergeApprovalRequestBody"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/RequestAccountMergeApprovalRequestBody"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/RequestAccountMergeApprovalRequestBody"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RequestAccountMergeApprovalResponse"
}
}
},
"description": "OK"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Conflict"
}
},
"summary": "Enqueue this merge for its surviving member's organisation to approve before it can\r\ncommit (EPIC 7 governance seam, debt-2026-07-09-284). Flags the merge require-approval\r\nand feeds the org-console approval queue via an outbox integration event. Only the\r\nsession initiator may request approval.",
"tags": [
"AccountMerge"
]
}
},
"/api/v1/account/merge/{id}/reverse": {
"post": {
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ReverseMergeResponse"
}
}
},
"description": "OK"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Conflict"
}
},
"summary": "Reverse a committed merge within the grace window, returning the full reversal\r\nreceipt (journey Step-7 \"Undo merge\", debt-2026-07-07-104). Exposed at the absolute\r\nroute the delivered client calls — `POST /api/v1/account/merge/{id}/reverse`.\r\nRestores both accounts,\r\ninstructs downstream consumers (via the reversal outbox event) to revert re-pointed\r\ngrants and retract org notices, and reports the counts of each. Only the session\r\ninitiator may reverse it; valid only while `ReversibleUntil` is open (else 409).",
"tags": [
"AccountMerge"
]
}
},
"/api/v1/account/merge/{id}/reversibility": {
"get": {
"description": "\n\r\n Answerable before the destructive confirm. That is the point of it: the\r\n confirm gate used to promise an unconditional 30-day self-service undo and the\r\n receipt then walked it back to \"(assisted recovery)\" — after the member could no\r\n longer decline. Both surfaces now render one posture resolved here.\r\n \r\n\n\r\n The posture is derived from what the reversal path actually enforces (the same\r\n resolved org policy `POST {id}/reverse` applies), so it can neither over-claim\r\n nor — as the client's unavailable-read fallback had to — under-claim.\r\n \r\n\nOnly the session initiator may read it. Zero-knowledge: a posture and a window length.",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AccountMergeReversibilityResult"
}
}
},
"description": "OK"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
}
},
"summary": "Resolve the reversal posture that applies to THIS merge — `self-service`,\r\n`assisted-only` or `none`, with the window length in whole days (journey\r\n`account-merge-consolidate-duplicate-identities`, gap G-reversibility,\r\ndebt-2026-08-10-003).",
"tags": [
"AccountMerge"
]
}
},
"/api/v1/account/merge/{id}/withdraw-approval": {
"post": {
"description": "\n\r\n This is the server half of the member's \"submit-then-override\" guard. The client\r\n releases the override only when this call succeeds: the behaviour it replaces\r\n cleared a device-local record and unlocked the override on a no-op, leaving the\r\n organisation holding a decision about a merge that had already run.\r\n \r\n\n\r\n 409 is returned when there is nothing to retract — the merge already committed\r\n or was undone, no request was ever made, or the organisation has already decided it.\r\n Withdrawing an already-withdrawn request returns 200, so a retried call reads\r\n as the success it is.\r\n ",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WithdrawAccountMergeApprovalResponse"
}
}
},
"description": "OK"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Conflict"
}
},
"summary": "Retract a queued org-approval request on the member's own initiative, before the\r\norganisation has decided it (gap G-withdraw, `uxf-2026-08-12-017`). Moves\r\nthe merge's approval state to `Withdrawn` and drops the org-console queue's held\r\ndecision via an outbox integration event. Only the session initiator may withdraw.",
"tags": [
"AccountMerge"
]
}
},
"/api/v1/account/support-agent-invitations": {
"get": {
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/SupportAgentInvitationDto"
},
"type": "array"
}
}
},
"description": "OK"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
}
},
"summary": "The caller's pending invitations, oldest first. Empty when the caller's address is not\r\nverified — an unverified address proves nothing about who holds it.",
"tags": [
"SupportAgentInvitations"
]
}
},
"/api/v1/account/support-agent-invitations/{agentId}/accept": {
"post": {
"parameters": [
{
"in": "path",
"name": "agentId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SupportAgentInvitationDto"
}
}
},
"description": "OK"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Conflict"
}
},
"summary": "Accept one pending invitation: the caller becomes the application's agent (`status: active`).\r\n404 `support-agent-invitation-not-found` for anything that is not the caller's pending\r\ninvitation; 409 when the caller is already one of the application's agents.",
"tags": [
"SupportAgentInvitations"
]
}
},
"/api/v1/account/support-agent-invitations/{agentId}/decline": {
"post": {
"parameters": [
{
"in": "path",
"name": "agentId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SupportAgentInvitationDto"
}
}
},
"description": "OK"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
}
},
"summary": "Decline one pending invitation: the roster shows it `declined` and nobody is named; only\r\nthe administrator inviting the address again reopens it. 404\r\n`support-agent-invitation-not-found` for anything that is not the caller's pending\r\ninvitation — the same single answer as accept.",
"tags": [
"SupportAgentInvitations"
]
}
},
"/api/v1/admin/setup-posture/backfill": {
"post": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/BackfillSetupPostureRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/BackfillSetupPostureRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/BackfillSetupPostureRequest"
}
}
},
"description": "Cursor, page size and dry-run flag."
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BackfillSetupPostureResult"
}
}
},
"description": "OK"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
}
},
"summary": "Announces one keyset page of accounts' setup posture. Call repeatedly, passing the returned\r\n`nextAfterId`, until `complete` is true.",
"tags": [
"AdminSetupPosture"
]
}
},
"/api/v1/admin/test-tenants": {
"post": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/CreateTestTenantRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateTestTenantRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/CreateTestTenantRequest"
}
}
},
"description": "Email (must be under the reserved browser-test domain),\r\n client-derived password hash, and optional sovereign home region."
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateTestTenantResult"
}
}
},
"description": "OK"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden"
}
},
"summary": "Provisions a verified `@browsertest.essence.digital` test-tenant account with\r\nthe `TestTenant` role. Platform-admin only.",
"tags": [
"TestTenants"
]
}
},
"/api/v1/admin/users": {
"get": {
"parameters": [
{
"in": "query",
"name": "query",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "page",
"schema": {
"default": 1,
"format": "int32",
"type": "integer"
}
},
{
"in": "query",
"name": "pageSize",
"schema": {
"default": 25,
"format": "int32",
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AdminUserPageDto"
}
}
},
"description": "OK"
}
},
"summary": "Paginated directory search over email and name.",
"tags": [
"AdminUsersDirectory"
]
}
},
"/api/v1/admin/users/{idOrEmail}/roles": {
"post": {
"parameters": [
{
"description": "A user id (GUID) or email address.",
"in": "path",
"name": "idOrEmail",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/SetUserRoleRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/SetUserRoleRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/SetUserRoleRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SetUserRoleResult"
}
}
},
"description": "OK"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
}
},
"summary": "Grants request.Role to the user identified by idOrEmail.",
"tags": [
"AdminUserRoles"
]
}
},
"/api/v1/admin/users/{idOrEmail}/roles/{role}": {
"delete": {
"parameters": [
{
"description": "A user id (GUID) or email address.",
"in": "path",
"name": "idOrEmail",
"required": true,
"schema": {
"type": "string"
}
},
{
"description": "Role name to revoke.",
"in": "path",
"name": "role",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SetUserRoleResult"
}
}
},
"description": "OK"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
}
},
"summary": "Revokes role from the user identified by idOrEmail.",
"tags": [
"AdminUserRoles"
]
}
},
"/api/v1/admin/users/{userId}": {
"get": {
"parameters": [
{
"in": "path",
"name": "userId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AdminUserSummaryDto"
}
}
},
"description": "OK"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
}
},
"summary": "One user's identity and setup summary.",
"tags": [
"AdminUsersDirectory"
]
}
},
"/api/v1/advice-agencies": {
"get": {
"parameters": [
{
"description": "Include agencies whose recognition has been withdrawn.",
"in": "query",
"name": "includeWithdrawn",
"schema": {
"default": false,
"type": "boolean"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/AdviceAgencyRow"
},
"type": "array"
}
}
},
"description": "The register."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The caller is not a platform administrator."
}
},
"summary": "The advice-agency register.",
"tags": [
"AdviceAgencies"
]
},
"post": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/RecogniseAdviceAgencyRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/RecogniseAdviceAgencyRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/RecogniseAdviceAgencyRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AdviceAgencyRow"
}
}
},
"description": "The agency's register row."
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The request failed validation."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The caller is not a platform administrator."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The organisation is already on the register."
}
},
"summary": "Recognises an organisation as an advice agency.",
"tags": [
"AdviceAgencies"
]
}
},
"/api/v1/advice-agencies/{organizationId}/adviser-capabilities": {
"put": {
"description": "The set is a ceiling, never a grant. A relying service intersects it with what the\r\nclient's own delegation conveyed, so widening it here can never authorise something a client\r\ndid not consent to; narrowing it takes effect for every live case of the agency at once.",
"parameters": [
{
"in": "path",
"name": "organizationId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/SetAdviceAgencyCapabilitiesRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/SetAdviceAgencyCapabilitiesRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/SetAdviceAgencyCapabilitiesRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AdviceAgencyRow"
}
}
},
"description": "The agency's updated register row."
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The capability set is empty or malformed."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The caller is not a platform administrator."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The organisation is not on the register."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The agency's recognition is suspended or withdrawn."
}
},
"summary": "Replaces an agency's adviser permission ceiling — the set defined once at agency level\r\nrather than re-chosen by each client.",
"tags": [
"AdviceAgencies"
]
}
},
"/api/v1/advice-agencies/{organizationId}/standing": {
"post": {
"description": "A withdrawal de-authorises every adviser of the agency at once — authorisation is read as a\r\nconjunction, so no adviser row is rewritten — and reconciles their role claims, which are\r\ncached projections a still-valid token would otherwise carry past the withdrawal.",
"parameters": [
{
"in": "path",
"name": "organizationId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/ChangeAdviceAgencyStandingRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/ChangeAdviceAgencyStandingRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ChangeAdviceAgencyStandingRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AdviceAgencyRow"
}
}
},
"description": "The agency's updated register row."
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unknown action, or a reason is missing where one is required."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The caller is not a platform administrator."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The organisation is not on the register."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The transition is unavailable from the current standing."
}
},
"summary": "Suspends, restores or withdraws an agency's recognition.",
"tags": [
"AdviceAgencies"
]
}
},
"/api/v1/advice-agency/advisers": {
"get": {
"parameters": [
{
"description": "Include revoked registrations (the audit view).",
"in": "query",
"name": "includeInactive",
"schema": {
"default": false,
"type": "boolean"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProfessionalAdviserRegisterResult"
}
}
},
"description": "The register plus its header counts and the agency permission set."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No organisation claim, or the organisation is not a recognised agency."
}
},
"summary": "The calling agency's own adviser register.",
"tags": [
"AdviceAgencyAdvisers"
]
},
"post": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/RegisterProfessionalAdviserRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/RegisterProfessionalAdviserRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/RegisterProfessionalAdviserRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProfessionalAdviserRow"
}
}
},
"description": "The adviser's register row."
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The request failed validation."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No organisation claim, or the organisation is not a recognised agency."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No account exists for the supplied adviser user id."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The agency's recognition is suspended or withdrawn."
}
},
"summary": "Registers an individual onto the calling agency's adviser register, unverified.",
"tags": [
"AdviceAgencyAdvisers"
]
}
},
"/api/v1/advice-agency/advisers/{adviserUserId}/accreditation": {
"put": {
"description": "Separate from identity verification: one establishes who they are, the other what they are\r\naccredited to do, and an agency commonly learns them at different moments. A creditor asked\r\nto accept a moratorium instruction is entitled to know which individual accreditation stands\r\nbehind it, which the agency's own firm permission does not answer.",
"parameters": [
{
"in": "path",
"name": "adviserUserId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/RecordAdviserAccreditationRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/RecordAdviserAccreditationRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/RecordAdviserAccreditationRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProfessionalAdviserRow"
}
}
},
"description": "The adviser's updated register row."
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The request failed validation."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No organisation claim, or the organisation is not a recognised agency."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No such adviser is on this agency's register."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The registration has been revoked, or recognition is not in good standing."
}
},
"summary": "Records or updates an adviser's own professional accreditation with their regulator.",
"tags": [
"AdviceAgencyAdvisers"
]
}
},
"/api/v1/advice-agency/advisers/{adviserUserId}/standing": {
"post": {
"description": "\n\r\n A revocation is accepted even while the agency's own recognition is suspended: being unable\r\n to strike off a compromised adviser because your recognition lapsed would trap an agency at\r\n exactly the moment it most needs to act. It also ends every live case that adviser held\r\n with this agency, leaving those clients visibly unassigned rather than nominally\r\n advised by somebody who has left.\r\n \r\n\n\r\n A stand-down deliberately does not touch the caseload. A client whose adviser is on\r\n leave needs a named successor, so the handover stays an act a supervisor performs.\r\n ",
"parameters": [
{
"in": "path",
"name": "adviserUserId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/ChangeProfessionalAdviserStandingRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/ChangeProfessionalAdviserStandingRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ChangeProfessionalAdviserStandingRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProfessionalAdviserRow"
}
}
},
"description": "The adviser's updated register row."
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unknown action, or a reason is missing where one is required."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No organisation claim, or the organisation is not on the register."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No such adviser is on this agency's register."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The transition is unavailable from the current standing."
}
},
"summary": "Stands an adviser down, reinstates them, or revokes their registration.",
"tags": [
"AdviceAgencyAdvisers"
]
}
},
"/api/v1/advice-agency/advisers/{adviserUserId}/verification": {
"post": {
"parameters": [
{
"in": "path",
"name": "adviserUserId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/VerifyProfessionalAdviserRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/VerifyProfessionalAdviserRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/VerifyProfessionalAdviserRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProfessionalAdviserRow"
}
}
},
"description": "The adviser's updated register row."
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The request failed validation."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No organisation claim, or the organisation is not a recognised agency."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No such adviser is on this agency's register."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The registration has been revoked, or recognition is not in good standing."
}
},
"summary": "Records that the adviser's identity has been verified, issuing the\r\n`professional-adviser` claim and making them assignable to a client case.",
"tags": [
"AdviceAgencyAdvisers"
]
}
},
"/api/v1/advice-agency/caseload": {
"get": {
"parameters": [
{
"description": "Optional filter to one client — the \"which of this agency's advisers held this case\" read a\r\nregulator asks for. Combine with includeClosed for the full history.",
"in": "query",
"name": "clientUserId",
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"description": "Include closed and handed-over assignments.",
"in": "query",
"name": "includeClosed",
"schema": {
"default": false,
"type": "boolean"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AdviserCaseloadResult"
}
}
},
"description": "The caseload."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No organisation claim, or the organisation is not on the register."
}
},
"summary": "The calling agency's caseload.",
"tags": [
"AdviceAgencyAdvisers"
]
},
"post": {
"description": "Refused when the agency already has a live assignment for this client: opening a second one\r\nwould leave two advisers each believing they hold the case. Hand it over instead, so the\r\nchange of hands is recorded.",
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/AssignAdviserToCaseRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/AssignAdviserToCaseRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/AssignAdviserToCaseRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AdviserCaseAssignmentRow"
}
}
},
"description": "The new assignment."
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The request failed validation."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No organisation claim, or the organisation is not a recognised agency."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The adviser is not currently authorised, or the client already has a live assignment."
}
},
"summary": "Puts a named adviser on a client's case.",
"tags": [
"AdviceAgencyAdvisers"
]
}
},
"/api/v1/advice-agency/caseload/{clientUserId}/end": {
"post": {
"parameters": [
{
"in": "path",
"name": "clientUserId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/EndAdviserCaseAssignmentRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/EndAdviserCaseAssignmentRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/EndAdviserCaseAssignmentRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AdviserCaseAssignmentRow"
}
}
},
"description": "The closed assignment."
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The request failed validation."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No organisation claim, or the organisation is not on the register."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "This agency holds no live assignment for the client."
}
},
"summary": "Closes a client's case with no successor.",
"tags": [
"AdviceAgencyAdvisers"
]
}
},
"/api/v1/advice-agency/caseload/{clientUserId}/reassign": {
"post": {
"parameters": [
{
"in": "path",
"name": "clientUserId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/ReassignAdviserCaseRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/ReassignAdviserCaseRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ReassignAdviserCaseRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AdviserCaseAssignmentRow"
}
}
},
"description": "The successor's assignment."
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The request failed validation."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No organisation claim, or the organisation is not a recognised agency."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "This agency holds no live assignment for the client."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The successor is not currently an authorised adviser of this agency."
}
},
"summary": "Hands a client's case from its current adviser to another adviser of the same agency — the\r\ncaseload reassignment the journey needs when an adviser goes on leave or leaves.",
"tags": [
"AdviceAgencyAdvisers"
]
}
},
"/api/v1/auth/account-closure-decisions/fraud": {
"post": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/DecideFraudClosureRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/DecideFraudClosureRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/DecideFraudClosureRequest"
}
}
}
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AccountClosureDecisionResult"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/AccountClosureDecisionResult"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/AccountClosureDecisionResult"
}
}
},
"description": "Decided; awaiting a different approver."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The caller may not decide a fraud closure."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The account is not open, or already has an open fraud closure."
}
},
"summary": "Decide a fraud closure (T7). Closes nothing until a different principal approves it.",
"tags": [
"AccountClosureDecisions"
]
}
},
"/api/v1/auth/account-closure-decisions/{id}": {
"get": {
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AccountClosureDecisionResult"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/AccountClosureDecisionResult"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/AccountClosureDecisionResult"
}
}
},
"description": "OK"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
}
},
"summary": "Read one closure decision.",
"tags": [
"AccountClosureDecisions"
]
}
},
"/api/v1/auth/account-closure-decisions/{id}/approve": {
"post": {
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AccountClosureDecisionResult"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/AccountClosureDecisionResult"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/AccountClosureDecisionResult"
}
}
},
"description": "OK"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Conflict"
}
},
"summary": "Approve a decided fraud closure or a verified death — by a different principal. Closes the account.",
"tags": [
"AccountClosureDecisions"
]
}
},
"/api/v1/auth/account-closure-decisions/{id}/reject": {
"post": {
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AccountClosureDecisionResult"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/AccountClosureDecisionResult"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/AccountClosureDecisionResult"
}
}
},
"description": "OK"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Conflict"
}
},
"summary": "Stop an open closure. Nothing is closed.",
"tags": [
"AccountClosureDecisions"
]
}
},
"/api/v1/auth/account-closure-decisions/{id}/verify-death": {
"post": {
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AccountClosureDecisionResult"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/AccountClosureDecisionResult"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/AccountClosureDecisionResult"
}
}
},
"description": "OK"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Conflict"
}
},
"summary": "Verify a reported death (T8, the Support lead). A different principal must approve it.",
"tags": [
"AccountClosureDecisions"
]
}
},
"/api/v1/auth/account-factor-holds/current": {
"get": {
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AccountFactorHoldView"
}
}
},
"description": "A hold is in force: the event it names, when it ends and how it can end."
},
"204": {
"description": "Nothing is held."
}
},
"summary": "The hold in force on the caller's text-message factor, if any.",
"tags": [
"AccountFactorHolds"
]
}
},
"/api/v1/auth/account-factor-holds/{holdId}/confirm": {
"post": {
"parameters": [
{
"in": "path",
"name": "holdId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AccountFactorHoldView"
}
}
},
"description": "Released; text-message codes work again."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "This session cannot end the hold: sign in with a passkey, or use a device trusted before it."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No such hold is in force on this account."
}
},
"summary": "Ends the hold: the caller confirms the number change was theirs.",
"tags": [
"AccountFactorHolds"
]
}
},
"/api/v1/auth/account/closure/cancel": {
"post": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/AccountClosureCancelRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/AccountClosureCancelRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/AccountClosureCancelRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AccountClosureCancelResponse"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/AccountClosureCancelResponse"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/AccountClosureCancelResponse"
}
}
},
"description": "The link was live: the closure is cancelled and the account is open."
},
"410": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The link cannot be used — the same answer whatever the reason."
}
},
"summary": "Cancel the closure the link was minted for, and reopen the account.",
"tags": [
"AccountClosureCancel"
]
}
},
"/api/v1/auth/account/deactivate": {
"post": {
"description": "The closure schedules the crypto-shred of the account's wrapped keys, recovery shares and\r\nciphertext for the end of the 14-day grace window (DVS-7.2), so a bearer token alone is not\r\nenough: a fresh (≤ 5 minutes) `act=account-deactivation` elevation on `X-Step-Up-Token`\r\n(Essence.Identity.Auth.Api.Security.IAccountClosureStepUpGate), proved with a passkey, an authenticator-app or\r\ntext-message code, or the password for an account with none of those; never an emailed or backup\r\ncode. The closure alert's email carries a single-use link that cancels it until\r\nEssence.Identity.Auth.Application.Commands.DeactivateUserResult.CancelBy (`POST account/closure/cancel`), because a closed\r\naccount cannot sign in.",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeactivateUserResult"
}
}
},
"description": "Account closed"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized, or no acceptable step-up elevation (`step-up-required`)"
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No cancel link could be minted, so nothing was closed"
}
},
"summary": "Closes the authenticated user's account at their own request (holder-account lifecycle procedure\r\n§3 T5). Requires a fresh GPG 44 medium step-up (DVS-7.2b).",
"tags": [
"Auth"
]
}
},
"/api/v1/auth/assisted-recovery/individual/requests/{caseRef}/cancel": {
"post": {
"parameters": [
{
"in": "path",
"name": "caseRef",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/IndividualRecoveryCancelBody"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/IndividualRecoveryCancelBody"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/IndividualRecoveryCancelBody"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IndividualRecoveryCancelResponse"
}
}
},
"description": "The recovery was stopped."
},
"410": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The link cannot be used — the same answer whatever the reason."
}
},
"summary": "Cancel from the hold notice's link. Never staged off and never gated by a release stage.",
"tags": [
"IndividualAssistedRecovery"
]
}
},
"/api/v1/auth/assisted-recovery/individual/requests/{caseRef}/complete": {
"post": {
"parameters": [
{
"in": "path",
"name": "caseRef",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/IndividualRecoveryCompleteBody"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/IndividualRecoveryCompleteBody"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/IndividualRecoveryCompleteBody"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IndividualRecoveryCompleteResponse"
}
}
},
"description": "Recovered. Sign in with the new password and set up a second factor."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not accepted — the same answer whatever the reason."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The hold has not ended; `holdEndsAt` says when it does."
}
},
"summary": "Complete after the hold: a new password verifier; every old authenticator and session revoked.",
"tags": [
"IndividualAssistedRecovery"
]
}
},
"/api/v1/auth/assisted-recovery/individual/requests/{caseRef}/proof": {
"post": {
"parameters": [
{
"in": "path",
"name": "caseRef",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/IndividualRecoveryProofBody"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/IndividualRecoveryProofBody"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/IndividualRecoveryProofBody"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IndividualRecoveryProofResponse"
}
}
},
"description": "Both codes were right: the hold has started."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not accepted — the same answer whatever the reason."
}
},
"summary": "Prove both codes. Starts the hold and returns the completion token, once.",
"tags": [
"IndividualAssistedRecovery"
]
}
},
"/api/v1/auth/assisted-recovery/requests": {
"post": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/AssistedRecoveryRequestBody"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/AssistedRecoveryRequestBody"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/AssistedRecoveryRequestBody"
}
}
}
},
"responses": {
"202": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AssistedRecoveryRequestResponse"
}
}
},
"description": "Accepted"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
}
},
"summary": "Raise a delegated assisted-recovery request. Always returns `202 Accepted`\r\nwith an opaque request reference for a well-formed request — a deliberate\r\nenumeration-safety property (the caller cannot distinguish a real managed\r\nidentity from an unknown/unmanaged one). A malformed body returns `400`\r\nvia the platform ProblemDetails handler (API-003) — including a `reason` the\r\nendpoint does not recognise, which is refused rather than rewritten (#8916). Omitting\r\n`reason` altogether is still accepted and defaults to `locked`.",
"tags": [
"AssistedRecovery"
]
}
},
"/api/v1/auth/assisted-recovery/requests/{requestRef}": {
"get": {
"description": "\n\r\n `[AllowAnonymous]` (SEC-002, explicit and inherited from the class): the\r\n subject is locked out and holds no token, so the opaque request reference is\r\n the only credential available to them. Rate-limited under the platform default\r\n policy (`essence-default`) — annotated explicitly rather than relied on\r\n implicitly, because this endpoint's risk profile is materially different from\r\n the raise endpoint's.\r\n \r\n\n\r\n Zero-knowledge. The response carries the reference, the case status, the\r\n subject's own stated reason, a machine rejection-reason slug, and two\r\n timestamps. It carries no email, no organisation identity, no helpdesk approver\r\n identity, no proofing evidence and no key material.\r\n \r\n\n\r\n Security trade-off — stated, not hidden. The raise endpoint returns a\r\n uniform `202` with an opaque reference whether or not the work email\r\n resolves to a real managed identity. This endpoint makes those two cases\r\n distinguishable to the holder of a reference: a reference minted for a\r\n real managed identity resolves, while a synthetic one returns `404`. That\r\n is an account-existence / org-membership oracle for anyone who can submit an\r\n email and then poll the reference they were handed back. It was accepted rather\r\n than eliminated because the alternative — refusing the subject any view of\r\n their own case — is the gap this endpoint exists to close, and because the\r\n positive case is loud: minting a resolvable reference also creates a\r\n visible entry in that organisation's helpdesk queue, so the probe is not silent.\r\n The residual exposure is further bounded by per-IP rate limiting and by the\r\n reference being an unguessable 128-bit value (a reference cannot be\r\n enumerated, only replayed after being issued). A stricter,\r\n distributed, per-reference limiter for this endpoint is a real improvement that\r\n is NOT in place: the service currently registers only the platform default\r\n policy.\r\n ",
"parameters": [
{
"in": "path",
"name": "requestRef",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AssistedRecoveryStatusResponse"
}
}
},
"description": "OK"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
}
},
"summary": "Read the current state of a delegated assisted-recovery case — journey step 1b,\r\nthe logged-out, re-enterable status surface. Returns metadata only.",
"tags": [
"AssistedRecovery"
]
}
},
"/api/v1/auth/assisted-recovery/requests/{requestRef}/complete": {
"post": {
"description": "\n\r\n `[AllowAnonymous]` (SEC-002, explicit): the subject is by definition\r\n unable to authenticate — that is the situation being recovered from. The\r\n endpoint is not unauthenticated in effect: possession of the single-use\r\n recovery token bound to an authorised case IS the credential, and both\r\n conditions are checked server-side before anything is mutated.\r\n \r\n\n\r\n A helpdesk agent cannot complete a recovery here. No role, claim, or org\r\n membership grants access to this endpoint — there is nothing to grant, because\r\n it is anonymous. What it requires is the token minted by the escrow grant and\r\n bound to the case, which is not something authorising confers on the authoriser.\r\n \r\n\n\r\n Zero-knowledge.\r\n `newPasswordHash` is the client-derived verifier,\r\n the same contract as `POST /auth/change-password`. No plaintext credential\r\n and no key material is ever transmitted; the subject re-wraps their own keys\r\n on-device.\r\n \r\n\n\r\n Out-of-band delivery of the token to the subject is NOT implemented in this\r\n service. The escrow grant returns the token reference to the authorising\r\n admin; getting it to the locked-out subject is a Notifications-owned seam. This\r\n endpoint validates whatever token the subject presents — it does not, and must\r\n not, mint or resend one.\r\n ",
"parameters": [
{
"in": "path",
"name": "requestRef",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/CompleteAssistedRecoveryBody"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/CompleteAssistedRecoveryBody"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/CompleteAssistedRecoveryBody"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CompleteAssistedRecoveryResponse"
}
}
},
"description": "OK"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
}
},
"summary": "Complete a delegated assisted recovery — journey step 4. The subject redeems\r\nthe CC-061 authorise-only recovery token their helpdesk's authorisation minted\r\nand sets a new, client-derived credential.",
"tags": [
"AssistedRecovery"
]
}
},
"/api/v1/auth/device-approvals": {
"get": {
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/PendingDeviceApprovalDto"
},
"type": "array"
}
}
},
"description": "The caller's pending requests (possibly empty)."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized."
}
},
"summary": "Lists the caller's own pending new-device approval requests.",
"tags": [
"DeviceApprovals"
]
}
},
"/api/v1/auth/device-approvals/{id}/approve": {
"post": {
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"204": {
"description": "Approved."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The request belongs to another account."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No such request."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The request was already resolved."
}
},
"summary": "Approves a pending new-device request raised against the caller's account.",
"tags": [
"DeviceApprovals"
]
}
},
"/api/v1/auth/device-approvals/{id}/deny": {
"post": {
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"204": {
"description": "Denied."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The request belongs to another account."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No such request."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The request was already resolved."
}
},
"summary": "Denies a pending new-device request raised against the caller's account.",
"tags": [
"DeviceApprovals"
]
}
},
"/api/v1/auth/discover": {
"post": {
"description": "\n\r\n Microsoft.AspNetCore.Authorization.AllowAnonymousAttribute — discovery necessarily runs BEFORE\r\n authentication.\r\n\n\r\n No credentials transit Global (FR-09.033). This endpoint issues a REDIRECT\r\n TARGET, nothing more. The completing instance authenticates the user and mints the token with\r\n its own `iss_instance`, which is what lets EPIC 3's `FederationTrustGate` govern\r\n downstream acceptance. Global never sees a password, an authorization code, or key material.\r\n \r\n\n\r\n Enumeration-safety in body AND timing (NFR-09.020). Every outcome — resolved,\r\n unknown identifier, unbound org host, registry unreachable — returns 200 with the identical\r\n response shape, and an unresolved lookup is answered with the region-default realm rather\r\n than an empty or error result. An unbound org host falls back to the registry's own\r\n default-region descriptor (a second registry call) specifically so the fallback carries a\r\n real signature: a fallback with an empty `realmToken` would be as good an oracle as a\r\n 404. Every response is then padded to a configured floor, because a registry hit does\r\n strictly more work than a miss and response time would otherwise leak what the body does\r\n not.\r\n\n\r\n Keyed on the DOMAIN, never the local-part (#8633). A submitted `email` is\r\n reduced to its domain in-process, and only the domain reaches the registry; the address is\r\n never stored, logged, or forwarded. Clients that prefer not to send the address at all may\r\n supply `domain` directly. Resolution used to key on the SHA-256 of the whole address,\r\n which is no less zero-knowledge and was still an account-existence oracle — a hash does not\r\n anonymise an input the caller chooses, so the region came back as a statement about that\r\n named individual, disclosing which sovereign holds their vault to an anonymous stranger.\r\n FR-09.035 already keys org SSO discovery on the work-email domain only, for this reason.",
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/DiscoverRealmRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/DiscoverRealmRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/DiscoverRealmRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DiscoverRealmResponse"
}
}
},
"description": "The realm to broker to. Shape is identical for resolved and unresolved."
}
},
"summary": "Global home-realm discovery broker (EPIC 9 FR-09.032/033). Resolves a sign-in identifier — a\r\ngeneral user's email, or an org-branded `host` — against the EPIC 3 Global Registry\r\nonly, and returns where the sign-in should be brokered to complete: the resolved\r\ninstance's OIDC authorize endpoint, the registry-signed short-TTL realm descriptor, and an\r\nopaque continuation `state`.",
"tags": [
"Auth"
]
}
},
"/api/v1/auth/domain-detections": {
"get": {
"parameters": [
{
"in": "query",
"name": "domain",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DomainDetectionResult"
}
}
},
"description": "The detection run and the accounts it matched."
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No domain was supplied."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The caller carries no organisation claim, or the header contradicts it."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The caller's organisation holds no current ownership proof for that domain — which is\r\nalso the answer when the domain was never proven or belongs to another organisation."
}
},
"summary": "Returns the accounts detected on one of the caller's organisation's verified domains.",
"tags": [
"DomainDetections"
]
}
},
"/api/v1/auth/email/resend-otp": {
"post": {
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ResendEmailVerificationOtpResult"
}
}
},
"description": "Code sent (or a non-rate-limit no-op, e.g. already verified)."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized."
},
"429": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Resend rate limit exceeded."
}
},
"summary": "(Re)issues an in-app email-verification OTP for the authenticated user\r\n(in-app-otp-email-verification). Rate-limited per user per hour.",
"tags": [
"Auth"
]
}
},
"/api/v1/auth/email/resend-otp/by-email": {
"post": {
"description": "\n\r\n `[AllowAnonymous]` (SEC-002, explicit) for the same reason as its sibling: no session\r\n exists. The answer is the SAME on every path — registered or not, verified or not, inside\r\n the account's 5/hr allowance or past it — so this is not an existence oracle and a 200 is\r\n never a promise that a message was sent. The account's own allowance still governs\r\n delivery, and a per-address burst ceiling inside the handler bounds how fast a stranger\r\n can put mail in somebody else's inbox.\r\n ",
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/ResendEmailVerificationOtpByEmailRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/ResendEmailVerificationOtpByEmailRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ResendEmailVerificationOtpByEmailRequest"
}
}
}
},
"responses": {
"202": {
"description": "Request accepted. If that address needs verifying, a code is on its way."
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Malformed body."
},
"429": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Request ceiling reached for this address."
}
},
"summary": "Sends a fresh registration email-verification code to an address, WITHOUT a session\r\n(#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\r\nwhile the tab was closed.",
"tags": [
"Auth"
]
}
},
"/api/v1/auth/email/verify-otp": {
"post": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/VerifyEmailOtpRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/VerifyEmailOtpRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/VerifyEmailOtpRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/VerifyEmailOtpResult"
}
}
},
"description": "Email verified; rotated tokens returned."
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Incorrect, expired, or exhausted code."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized."
}
},
"summary": "Verifies the authenticated user's email using the in-app OTP code\r\n(in-app-otp-email-verification). On success the caller's session tokens are\r\nrotated so they reflect the verified state.",
"tags": [
"Auth"
]
}
},
"/api/v1/auth/email/verify-otp/by-email": {
"post": {
"description": "\n\r\n `[AllowAnonymous]` (SEC-002, explicit). The caller has, by definition, no session:\r\n that is the entire condition this endpoint exists to serve. Registration emails only the\r\n 6-digit code, and until this existed the ONLY endpoint that could spend it was the\r\n `[Authorize]` twin above — so closing the browser tab created an account that could\r\n neither be signed into (the address is unverified) nor re-registered (the address is\r\n taken). AC-44.006 / FR-44.003 promise a sign-up can be resumed after closing the browser;\r\n the onboarding session honoured that, this gate could not.\r\n \r\n\n\r\n It issues no session. On success the email is verified and the caller is told to\r\n sign in — no access token, no refresh token, no cookie. Possession of a mailbox proves an\r\n address; it does not authenticate a person, and a 6-digit emailed code must never become a\r\n factor that mints a session around the password.\r\n \r\n\n\r\n Uniform negatives. Unknown address, no outstanding code, wrong code, expired code,\r\n exhausted attempts and an already-verified address all return the IDENTICAL 400 — one\r\n title, no detail — so the response is not an oracle for the account's verification or code\r\n state, and since `POST /register` answers uniformly (#7225, on by default since DVS-4.12) it is one\r\n of the anonymous sign-up steps that must not tell a registered address from a new one either.\r\n \r\n\n\r\n Rate-limited twice: the platform default per IP (`essence-default`, SEC-004) and a\r\n per-address ceiling inside the handler that is charged before any lookup, so a caller past\r\n it costs nothing and an unregistered address reaches it at the same count as a registered\r\n one. The outstanding code keeps its own per-code attempt cap underneath both.\r\n ",
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/VerifyEmailOtpByEmailRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/VerifyEmailOtpByEmailRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/VerifyEmailOtpByEmailRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/VerifyEmailOtpByEmailResponse"
}
}
},
"description": "Code accepted; the email is now verified. Sign in to continue."
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Malformed body, or the code was not accepted (uniform)."
},
"429": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Attempt ceiling reached for this address."
}
},
"summary": "Redeems a registration email-verification code WITHOUT a session (#7539) — the route back\r\nfor someone who closed the tab at the email gate.",
"tags": [
"Auth"
]
}
},
"/api/v1/auth/federated-accounts/uae-pass": {
"post": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/UaePassAccountLinkRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/UaePassAccountLinkRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/UaePassAccountLinkRequest"
}
}
},
"description": "The subject and the home region of a new account."
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UaePassAccountLinkResponse"
}
}
},
"description": "The account the subject is linked to; `isNewUser` when this call created it."
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The subject is missing or malformed."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No valid bearer token."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The caller is not the UAE Pass account linker, or the linked account is deactivated (`reason: federated_account_deactivated`)."
}
},
"summary": "Resolves (or provisions) the Essence account behind a verified UAE Pass subject.",
"tags": [
"FederatedAccountLink"
]
}
},
"/api/v1/auth/identity-attested-reprovision": {
"post": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/IdentityAttestedReprovisionRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/IdentityAttestedReprovisionRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/IdentityAttestedReprovisionRequest"
}
}
},
"description": "The subject, the verification, and the client-derived credential hash."
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IdentityAttestedReprovisionResult"
}
}
},
"description": "The credential set was bootstrapped. The attestation names the verifier, the evidence kinds\r\nthe platform holds a record of, the level reached, when, and the EPIC 4 audit anchor."
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The request failed validation."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No completed, in-window verification authorises a re-provision for this account. Returned\r\nidentically for every cause, deliberately."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Recovery material still survives (or could not be ruled out), the verification fell below\r\nthe assurance floor, or it has already authorised a re-provision."
}
},
"summary": "Bootstraps a fresh credential set authorised by a completed identity verification, and\r\nreturns the immutable attestation binding the two together.",
"tags": [
"IdentityAttestedReprovision"
]
}
},
"/api/v1/auth/invitations/accept": {
"post": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/AcceptInvitationCommand"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/AcceptInvitationCommand"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/AcceptInvitationCommand"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AcceptInvitationResult"
}
}
},
"description": "Account provisioned; authenticated session issued."
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No invitation resolves the token."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invitation not actionable, or an account already exists for the email."
}
},
"summary": "Accept an invitation: provision the invitee's account from the token +\r\non-device password hash (zero-knowledge) and return an authenticated session.",
"tags": [
"Invitations"
]
}
},
"/api/v1/auth/invitations/accept-as-member": {
"post": {
"description": "No account is created, no password is set and no device is registered — the caller already\r\nhas all three. The response carries a freshly minted access token for the caller's SAME\r\nsession, so the organisation's `org_id` claim is usable immediately rather than only\r\nafter the next refresh; the refresh token is untouched and the session continues.",
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/MemberInvitationTokenRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/MemberInvitationTokenRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/MemberInvitationTokenRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AcceptInvitationAsMemberResult"
}
}
},
"description": "Accepted; the returned access token carries the organisation."
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No token in the body."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not signed in."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No invitation of the signed-in account resolves the token."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The invitation is not actionable (already accepted, declined, expired or withdrawn), or the\r\ncaller already belongs to another organisation."
}
},
"summary": "Accept an invitation as the signed-in account it was issued to, joining that organisation.",
"tags": [
"MemberInvitationAcceptance"
]
}
},
"/api/v1/auth/invitations/decline": {
"post": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/DeclineInvitationCommand"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeclineInvitationCommand"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/DeclineInvitationCommand"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeclineInvitationResult"
}
}
},
"description": "Invitation declined."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No invitation resolves the token."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invitation not actionable (already accepted/declined/expired)."
}
},
"summary": "Decline an invitation by its token.",
"tags": [
"Invitations"
]
}
},
"/api/v1/auth/invitations/decline-as-member": {
"post": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/MemberInvitationTokenRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/MemberInvitationTokenRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/MemberInvitationTokenRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeclineInvitationResult"
}
}
},
"description": "Declined."
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No token in the body."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not signed in."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No invitation of the signed-in account resolves the token."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The invitation is not actionable (already accepted, declined, expired or withdrawn)."
}
},
"summary": "Decline an invitation as the signed-in account it was issued to.",
"tags": [
"MemberInvitationAcceptance"
]
}
},
"/api/v1/auth/invitations/register": {
"post": {
"description": "Admits only a first-party service principal named in\r\nEssence.Identity.Auth.Api.Controllers.InvitationIngestionPolicies.TrustedCallers (#11943). The body names the\r\norganisation, the invitee and the roles the accepted account is bound to, and nothing here can\r\ncheck those against a caller's own authority — so a user token, which bare `[Authorize]`\r\nadmitted, could mint an invitation into any organisation carrying any role.",
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/RegisterOrgInvitationCommand"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/RegisterOrgInvitationCommand"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/RegisterOrgInvitationCommand"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RegisterOrgInvitationResult"
}
}
},
"description": "OK"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
}
},
"summary": "Register an org invitation with EPIC 9's accountless-acceptance store. This\r\nis the service-to-service ingestion the org-side invitation seam calls when\r\nit mints the token. Idempotent by invitation id.",
"tags": [
"Invitations"
]
}
},
"/api/v1/auth/invitations/{token}": {
"get": {
"parameters": [
{
"in": "path",
"name": "token",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InvitationDetailDto"
}
}
},
"description": "Invitation detail (including sponsored-Premium context when present)."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No invitation resolves the token."
}
},
"summary": "Read an invitation's detail by its opaque token — the invitation-detail card\r\nthe essence-web AcceptInvitationPage renders before acceptance.",
"tags": [
"Invitations"
]
}
},
"/api/v1/auth/login": {
"post": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/LoginCommand"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/LoginCommand"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/LoginCommand"
}
}
},
"description": "Login request"
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/LoginResult"
}
}
},
"description": "Login successful"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid request data"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid credentials or account locked"
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Conflict"
}
},
"summary": "Authenticates a user and returns access/refresh tokens.",
"tags": [
"Auth"
]
}
},
"/api/v1/auth/login-methods": {
"get": {
"parameters": [
{
"description": "Completing instance region (ISO-3166 alpha-2, e.g. \"GB\"). Optional — an\r\n empty/missing region falls back to the universal method set (passkey + email) rather than a\r\n validation error, since ApiController model binding would otherwise reject a non-nullable\r\n string as a required field.",
"in": "query",
"name": "region",
"schema": {
"type": "string"
}
},
{
"description": "Optional work-email domain (ZK — domain only, never local-part).",
"in": "query",
"name": "domain",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/LoginMethodsResponse"
}
}
},
"description": "OK"
}
},
"summary": "Region-aware login-method presentation policy (EPIC 9 FR-09.036). Returns the\r\nordered list of login methods the completing instance should present for a\r\ngiven region — organisation enterprise SSO first (when a federated + entitled\r\nwork-email `domain` is supplied), then the region national IdP\r\n(AE → UAE PASS, GB → GOV.UK One Login), then passkey + email — honouring the\r\norg's SSO-only enforcement. The login UI renders from this list instead of a\r\nhardcoded button set. Anti-enumeration: an unknown/unfederated domain simply\r\nyields the general-user list (no org SSO), identical to supplying no domain.",
"tags": [
"Auth"
]
}
},
"/api/v1/auth/login/device-approval/{token}": {
"get": {
"parameters": [
{
"description": "The opaque approval-poll token.",
"in": "path",
"name": "token",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PollDeviceApprovalResult"
}
}
},
"description": "Current status (with tokens on the first approved poll)."
}
},
"summary": "Polls the outcome of a Tier A new-device approval request (spec §5.1). The new device calls\r\nthis with the opaque token from the login response; while a trusted device has not yet decided\r\nit returns `{ status: \"pending\" }`. On the first `approved` poll it issues the session\r\ntokens exactly once; subsequent polls return `approved` without re-issuing.",
"tags": [
"Auth"
]
}
},
"/api/v1/auth/login/device-limit": {
"post": {
"description": "Microsoft.AspNetCore.Authorization.AllowAnonymousAttribute (SEC-002, explicit): the person has proved their\r\n factors but holds no session on this device yet. Authorisation is possession of the\r\n single-use `deviceLimit.challengeToken`, the same footing as `login/mfa`. A choice\r\n that frees nothing answers `200` with `deviceLimitReached` and a rotated token.",
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/ContinueAfterDeviceLimitCommand"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/ContinueAfterDeviceLimitCommand"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ContinueAfterDeviceLimitCommand"
}
}
},
"description": "The pause's challenge token and the devices to sign out."
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/LoginResult"
}
}
},
"description": "Session issued, or still at the limit (see `deviceLimitReached`)."
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid request data."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The challenge is unknown, used or expired."
}
},
"summary": "Continues a sign-in paused at the device allowance (ruling 2026-10-01): signs out the\r\nchosen devices and, if that frees a place, issues the session the paused sign-in earned.",
"tags": [
"Auth"
]
}
},
"/api/v1/auth/login/mfa": {
"post": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/CompleteMfaLoginCommand"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/CompleteMfaLoginCommand"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/CompleteMfaLoginCommand"
}
}
},
"description": "The MFA challenge token and second-factor code."
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/LoginResult"
}
}
},
"description": "MFA verified; session issued."
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid request data."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid/expired challenge or incorrect code."
}
},
"summary": "Completes a login that required multi-factor authentication.",
"tags": [
"Auth"
]
}
},
"/api/v1/auth/login/mfa/resend": {
"post": {
"description": "\n\r\n Microsoft.AspNetCore.Authorization.AllowAnonymousAttribute (SEC-002, explicit): the caller has cleared the\r\n password factor but has no session yet, so the authenticated send endpoints\r\n (`POST /api/v1/mfa/send/email`) are unreachable to it. Authorisation is possession of\r\n the pending challenge token — the same credential `login/mfa` accepts on this same\r\n anonymous footing, and the reason the verify screen previously had no resend at all.\r\n \r\n\n\r\n Always `200`, including when nothing was sent. The outcome is in\r\n `status` (an `OtpDeliveryStatus`): the whole point of this endpoint is that a\r\n screen can tell a rate limit from an expired attempt from a dead channel and say the right\r\n thing, which a bare 4xx cannot express. It also means a caller cannot use the status code to\r\n distinguish a live challenge token from a dead one.\r\n ",
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/ResendLoginMfaCodeCommand"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/ResendLoginMfaCodeCommand"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ResendLoginMfaCodeCommand"
}
}
},
"description": "The pending challenge token from the login response."
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ResendLoginMfaCodeResult"
}
}
},
"description": "Resend outcome — see `status`; `sent` may be false."
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid request data."
}
},
"summary": "Re-issues the one-time code for a login that is paused on its second factor (#6166).",
"tags": [
"Auth"
]
}
},
"/api/v1/auth/logout": {
"post": {
"description": "The request body is optional. A browser SPA has no refresh token\r\navailable to JavaScript (it never leaves the httpOnly cookie / server),\r\nso its logout call sends NO body at all — it identifies the session\r\npurely from the caller's own JWT/cookie. When no refresh token is\r\nsupplied, the caller MUST be authenticated; the session is then\r\nresolved from the authenticated access token's `jti` claim, never\r\nfrom client input. Callers that DO send a valid\r\n`{ \"refreshToken\": \"...\" }` body keep working exactly as before,\r\nwithout needing to be authenticated (e.g. logging out with an already-\r\nexpired access token but a still-valid refresh token).",
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/LogoutCommand"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/LogoutCommand"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/LogoutCommand"
}
}
},
"description": "Logout request (optional — omit for a bodyless authenticated logout)"
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/LogoutResult"
}
}
},
"description": "Logout successful"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid request data"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No refresh token supplied and the caller is not authenticated"
}
},
"summary": "Logs out a user by revoking the session.",
"tags": [
"Auth"
]
}
},
"/api/v1/auth/mfa/otp/request": {
"post": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/RecoveryOtpRequestDto"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/RecoveryOtpRequestDto"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/RecoveryOtpRequestDto"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RecoveryOtpRequestResponse"
}
}
},
"description": "OK"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"429": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Too Many Requests"
}
},
"summary": "Send a step-up one-time code over the chosen recovery channel.",
"tags": [
"StepUpOtp"
]
}
},
"/api/v1/auth/mfa/otp/verify": {
"post": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/RecoveryOtpVerifyDto"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/RecoveryOtpVerifyDto"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/RecoveryOtpVerifyDto"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RecoveryOtpVerifyResponse"
}
}
},
"description": "OK"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
}
},
"summary": "Verify a delivered step-up one-time code and, on success, receive the\r\n`recovery-initiate` elevation token it earns.",
"tags": [
"StepUpOtp"
]
}
},
"/api/v1/auth/oauth/{provider}/authorize": {
"post": {
"parameters": [
{
"description": "Identity provider (e.g., UaePass, AzureAD, Google)",
"in": "path",
"name": "provider",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "header",
"name": "X-Api-Version",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/InitiateOAuthRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/InitiateOAuthRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/InitiateOAuthRequest"
}
}
},
"description": "OAuth initiation request"
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InitiateOAuthResult"
}
}
},
"description": "Authorization URL generated successfully"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid request parameters"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Identity provider not supported"
},
"501": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Provider is supported by the platform but has no usable credential on this instance, so the\r\nhand-off cannot complete and is refused rather than started (#6942)."
}
},
"summary": "Initiates OAuth authentication flow with an identity provider.\r\nReturns authorization URL with PKCE parameters for secure code exchange.",
"tags": [
"OAuth"
]
}
},
"/api/v1/auth/oauth/{provider}/callback": {
"post": {
"parameters": [
{
"description": "Identity provider",
"in": "path",
"name": "provider",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "header",
"name": "X-Api-Version",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/OAuthCallbackRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/OAuthCallbackRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/OAuthCallbackRequest"
}
}
},
"description": "OAuth callback data with authorization code"
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OAuthCallbackResult"
}
}
},
"description": "Authentication successful, tokens issued"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid request or authentication failed"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Identity provider not supported"
},
"501": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Provider is supported by the platform but has no usable credential on this instance, so the\r\nhand-off cannot be completed (#6529)."
}
},
"summary": "Handles OAuth callback after user authorization at identity provider.\r\nExchanges authorization code for tokens and signs in to, or creates, the account the\r\nexternal identity belongs to. It never links: linking an identity to an existing account\r\nstarts at the authenticated `{provider}/link/authorize` and completes at\r\n`{provider}/link`, and a state minted for a link is refused here.",
"tags": [
"OAuth"
]
}
},
"/api/v1/auth/oauth/{provider}/link": {
"post": {
"parameters": [
{
"description": "Identity provider to link",
"in": "path",
"name": "provider",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "header",
"name": "X-Api-Version",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/OAuthCallbackRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/OAuthCallbackRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/OAuthCallbackRequest"
}
}
},
"description": "OAuth callback data with authorization code"
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OAuthLinkResult"
}
}
},
"description": "Identity provider linked successfully"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid request or linking failed"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "User not authenticated"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Identity provider not supported"
},
"501": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Provider is supported by the platform but has no usable credential on this instance, so it\r\ncannot be linked (#6529)."
}
},
"summary": "Completes linking an OAuth identity provider to the authenticated user's account.\r\nAllows users to sign in using multiple identity providers. The state must have been\r\nstarted at `{provider}/link/authorize` by this same signed-in user; a sign-in state,\r\nor another user's link state, is refused before the authorization code is exchanged.",
"tags": [
"OAuth"
]
}
},
"/api/v1/auth/oauth/{provider}/link/authorize": {
"post": {
"parameters": [
{
"description": "Identity provider to link",
"in": "path",
"name": "provider",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "header",
"name": "X-Api-Version",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/InitiateOAuthLinkRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/InitiateOAuthLinkRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/InitiateOAuthLinkRequest"
}
}
},
"description": "Redirect URI and optional scopes"
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InitiateOAuthResult"
}
}
},
"description": "Authorization URL generated successfully"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid request parameters"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not authenticated, or no acceptable step-up elevation (`step-up-required`)"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The bearer token is a delegated or derived token"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Identity provider not supported"
},
"501": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Provider is supported by the platform but has no usable credential on this instance, so it\r\ncannot be linked (#6529)."
}
},
"summary": "Starts linking an identity provider to the signed-in user's account. Same hand-off as\r\n`{provider}/authorize`, except the one-time state records the caller (from the bearer\r\ntoken, never the body) as the account to link to — the only way a link can be started.\r\nComplete it at `{provider}/link`, signed in as the same user.\r\n\n\r\nRequires an `act=account-link` step-up elevation on `X-Step-Up-Token`\r\n(Essence.Identity.Auth.Api.Security.IOAuthLinkStepUpGate, D-131): a link is a lasting way into the account, so a\r\nsession alone is not authority for it. A delegated or otherwise derived token (any bearer\r\ncarrying `act`) is refused outright.\r\n",
"tags": [
"OAuth"
]
}
},
"/api/v1/auth/org-idp/resolve": {
"get": {
"parameters": [
{
"description": "Verified work-email domain, lower-cased. Optional — an empty or\r\n missing domain yields the same uniform `{ \"org\": null }` as an unfederated one.\r\n 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\r\n `region` (ISS-5): under `[ApiController]` a non-nullable `string` query\r\n parameter is implicitly required, so model validation would reject the empty case with a\r\n 400 before the guard below ever runs — leaving that guard unreachable and making the\r\n empty domain distinguishable from every other input, contrary to NFR-09.020.",
"in": "query",
"name": "domain",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OrgIdpResolveResponse"
}
}
},
"description": "OK"
}
},
"summary": "Organisation SSO directory resolution (EPIC 9 FR-09.035) — the server side of\r\nthe frontend `orgSsoResolution.ts` seam. Resolves the org IdP record from a\r\nverified work-email `domain` (ZK — keyed on the domain only, never the\r\nlocal-part). Returns `{ \"org\": null }` uniformly for an unknown OR a\r\nnon-federated/disabled domain so org existence is not enumerable (NFR-09.020).",
"tags": [
"Auth"
]
}
},
"/api/v1/auth/password/breach-range": {
"post": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/PasswordBreachRangeRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/PasswordBreachRangeRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/PasswordBreachRangeRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PasswordBreachRangeResponse"
}
}
},
"description": "The range: every suffix sharing the prefix, with counts (0 = padding)."
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The prefix is not exactly 5 upper-case hexadecimal characters."
},
"429": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Too many lookups from this address."
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The range could not be fetched; the device records `not_performed`."
}
},
"summary": "Return the padded suffix list for a 5-character SHA-1 prefix.",
"tags": [
"PasswordBreachRange"
]
}
},
"/api/v1/auth/password/change": {
"post": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/ChangePasswordRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/ChangePasswordRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ChangePasswordRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ChangePasswordResult"
}
}
},
"description": "Password changed, sessions revoked"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Current password incorrect or new password invalid"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
}
},
"summary": "Changes the authenticated user's password (FR-09.013). Requires\r\nthe current password for re-authentication. On success ALL of\r\nthe user's active sessions are revoked and the outstanding\r\naccess tokens blacklisted — the client must re-authenticate.",
"tags": [
"Auth"
]
}
},
"/api/v1/auth/password/set": {
"post": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/SetPasswordRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/SetPasswordRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/SetPasswordRequest"
}
}
}
},
"responses": {
"204": {
"description": "Password set"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Password hash missing or malformed"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Account already has a password — use `password/change`"
}
},
"summary": "Sets the FIRST password on the authenticated account when it has none\r\n(a social / passkey-only account). Sibling of `password/change`\r\n(FR-09.013) for accounts with no current credential to re-authenticate\r\nagainst. `passwordHash` is the client-derived hash — exactly as on\r\n`register` — never a plaintext password; the server wraps it in\r\nArgon2id before persisting. Sessions are NOT revoked.",
"tags": [
"Auth"
]
}
},
"/api/v1/auth/phone/verification": {
"post": {
"responses": {
"202": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PhoneVerificationSentResponse"
}
}
},
"description": "Sent; the masked number and when the code expires."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Nothing to send: no number on the account, already verified, or the email not yet verified."
},
"429": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Too many codes for this account, number or network; `Retry-After` says when."
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The text could not be sent; ask again."
}
},
"summary": "Texts a six-digit code, valid for ten minutes, to the number on the caller's account.",
"tags": [
"PhoneVerification"
]
}
},
"/api/v1/auth/phone/verification/confirm": {
"post": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/ConfirmPhoneVerificationRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConfirmPhoneVerificationRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ConfirmPhoneVerificationRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PhoneVerificationConfirmedResponse"
}
}
},
"description": "The number is verified."
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The code was not accepted: `reason` is `mismatch`, `expired`, `exhausted` or `no-code`."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The number is already verified, or there is none."
},
"429": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Too many attempts; `Retry-After` says when."
}
},
"summary": "Redeems the code. Single use; five attempts per code; ten attempts per hour per account.",
"tags": [
"PhoneVerification"
]
}
},
"/api/v1/auth/recipients/lookup": {
"post": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/RecipientLookupRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/RecipientLookupRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/RecipientLookupRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RecipientResolutionDto"
}
}
},
"description": "The lookup completed. `resolved=false` means no active account can receive a share at\r\nthat address — it does not say whether one exists."
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The body carried no email address."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No valid bearer token."
}
},
"summary": "Resolves an email address to a share-capable user principal.",
"tags": [
"RecipientLookup"
]
}
},
"/api/v1/auth/recovery-phrase": {
"delete": {
"description": "Requires a fresh (≤ 5 minutes) `act=recovery-settings-change` elevation (DVS-4.4c): removing\r\nthe phrase takes a way back into the account away from the holder.",
"responses": {
"204": {
"description": "Recovery proof cleared (or none was enrolled)"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized, or no acceptable step-up elevation (`step-up-required`)"
}
},
"summary": "Clears the authenticated user's recovery-phrase proof. Idempotent: clearing an\r\naccount with no proof enrolled also returns `204`.",
"tags": [
"Auth"
]
}
},
"/api/v1/auth/recovery-phrase/enrol": {
"post": {
"description": "Requires a fresh (≤ 5 minutes) `act=recovery-settings-change` elevation on\r\n`X-Step-Up-Token` (DVS-4.4c): whoever enrols a phrase can later recover the account with it.",
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/EnrolRecoveryPhraseRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/EnrolRecoveryPhraseRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/EnrolRecoveryPhraseRequest"
}
}
}
},
"responses": {
"204": {
"description": "Recovery proof enrolled"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Recovery proof missing or malformed"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized, or no acceptable step-up elevation (`step-up-required`)"
}
},
"summary": "Enrols (or re-enrols) the authenticated user's recovery-phrase proof.\r\n`recoveryProof` is the client-derived proof (hex, ≥ 64 chars) — never the\r\nphrase, never the seed; the server wraps it in Argon2id before persisting.\r\nRe-enrolment replaces the previous proof.",
"tags": [
"Auth"
]
}
},
"/api/v1/auth/recovery-phrase/token": {
"post": {
"description": "\n\r\n `[AllowAnonymous]` (SEC-002, explicit): the caller has, by definition, no session.\r\n Rate-limited under the platform default policy (`essence-default`, SEC-004) — the\r\n same policy every other anonymous credential surface in this service uses; a wrong\r\n proof against a real account also increments the account's brute-force lockout counter\r\n (FR-09.010/011), so this surface cannot be used to guess around the login lockout.\r\n \r\n\n\r\n Enumeration-safe. Unknown email, no recovery phrase enrolled, wrong proof,\r\n inactive and locked-out accounts all receive the IDENTICAL `401` ProblemDetails\r\n (`title = \"Recovery phrase not accepted\"`, no `detail`) after a full Argon2id\r\n verification, so neither the body nor the timing is an account-existence or\r\n recovery-enrolment oracle.\r\n \r\n\n\r\n Zero-knowledge. The proof is not the phrase and cannot derive the vault KEK; the\r\n token carries only opaque identifiers. Auth does not reset the password (FR-05.082).\r\n ",
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/RecoveryPhraseTokenRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/RecoveryPhraseTokenRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/RecoveryPhraseTokenRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RecoveryRewrapTokenResponse"
}
}
},
"description": "Proof accepted; one-shot re-wrap token issued"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Email or proof malformed"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Recovery phrase not accepted (uniform)"
},
"429": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "FR-01.009 attempt ceiling reached for this email"
}
},
"summary": "Verifies a recovery-phrase proof for a user who has forgotten their password and,\r\non success, mints the one-shot, 5-minute `purpose=recovery-rewrap` token that\r\nMultiDeviceSync accepts on `GET /api/v1/keys/wrapped-umk/recovery-phrase` and\r\n`POST /api/v1/keys/wrapped-umk/recovery-rewrap`.",
"tags": [
"Auth"
]
}
},
"/api/v1/auth/refresh": {
"post": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/RefreshTokenCommand"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/RefreshTokenCommand"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/RefreshTokenCommand"
}
}
},
"description": "Refresh token request"
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RefreshTokenResult"
}
}
},
"description": "Token refreshed successfully"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid request data"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid or expired refresh token"
}
},
"summary": "Refreshes an access token using a refresh token.",
"tags": [
"Auth"
]
}
},
"/api/v1/auth/register": {
"post": {
"description": "\n\r\n `[AllowAnonymous]` (SEC-002, explicit): the caller has no account yet, by definition.\r\n \r\n\n\r\n Uniform answer (#7225, EPIC 9 contract, when `Registration:UniformResponse` is\r\n on — the code default since DVS-4.12; staged off on Global, decision P-18). The response is `202``{ \"next\": \"verify-email\" }`, byte-identical for a\r\n free address and a taken one. The body is a constant built here: it does not depend on\r\n anything the handler learned, so the two cases cannot drift apart through it. No tokens\r\n and no cookie. The account's first session comes from sign-in, after the emailed code is\r\n redeemed at `POST email/verify-otp/by-email`. A per-address ceiling answers\r\n `429`, and it is charged before the lookup.\r\n \r\n\n\r\n Legacy answer (switch off).\r\n `200` with tokens, or `409` for a taken address.\r\n This is the disclosure #7225 removes. It remains only until the callers that read the\r\n tokens have migrated.\r\n ",
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/RegisterUserCommand"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/RegisterUserCommand"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/RegisterUserCommand"
}
}
},
"description": "Registration request"
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RegisterUserResult"
}
}
},
"description": "Legacy: user registered, tokens issued."
},
"202": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RegistrationAcceptedResponse"
}
}
},
"description": "Accepted: check your email (uniform; says nothing about the address)."
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid request data"
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Legacy: email already exists"
},
"428": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "DVS-4.12: this network has made many sign-ups this hour; solve `proofOfWork` and send again."
},
"429": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Registration ceiling reached for this address (uniform only)."
}
},
"summary": "Registers a new user account.",
"tags": [
"Auth"
]
}
},
"/api/v1/auth/registration/abandon": {
"post": {
"description": "\n\r\n The exit from the email-verification gate for someone who mistyped their address. Until\r\n this existed the screen offered \"sign out and register again\", and that advice could not\r\n be followed: the unverified `users` row still held the address, so\r\n `POST /register` refused it with 409. The address was burned — permanently, and most\r\n painfully when the typo landed on somebody else's real address.\r\n \r\n\n\r\n This releases; it does not amend. FR-44.024 originally asked for an in-place email\r\n change. The ruling on #7964 amended it, because on this platform the email is the PBKDF2\r\n salt behind both the stored credential and the UMK: amending it under a hash derived from\r\n the old address locks the user out and orphans their keys. Releasing costs the same\r\n password re-entry and risks nothing.\r\n \r\n\n\r\n Subject comes from the bearer token's `sub`, never the body (SEC-002 + the same\r\n pattern as `account/deactivate`) — a body-supplied id would make this an\r\n arbitrary-account eraser. Idempotent: releasing an already-released registration answers\r\n 204, because the effect the caller asked for is already true.\r\n ",
"responses": {
"204": {
"description": "Registration released; the address is free."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The address is already verified — changing it is an account-settings\r\n credential rotation, not this endpoint."
}
},
"summary": "Releases the authenticated user's unverified registration (#7964) so the address\r\nit holds can be registered again.",
"tags": [
"Auth"
]
}
},
"/api/v1/auth/revocation-snapshot": {
"get": {
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RevocationSnapshotDto"
}
}
},
"description": "OK"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
}
},
"summary": "Every revoked access token id that has not yet expired.",
"tags": [
"RevocationSnapshot"
]
}
},
"/api/v1/auth/session": {
"post": {
"responses": {
"204": {
"description": "Cookie session established."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No valid JWT in Authorization header."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Cookie session feature is disabled."
}
},
"summary": "Establishes an httpOnly cookie session from the current JWT.\r\nThe caller must present a valid JWT in the Authorization header.\r\nOn success, issues:\r\n - `essence_auth`: httpOnly + Secure + SameSite=Strict cookie\r\n containing the JWT.\r\n - `essence_csrf`: readable (non-httpOnly) + Secure +\r\n SameSite=Strict cookie containing a random CSRF token.\r\nReturns 204 No Content on success.",
"tags": [
"CookieSession"
]
}
},
"/api/v1/auth/session/me": {
"get": {
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SessionMeResponse"
}
}
},
"description": "User identity claims."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not authenticated."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Cookie session feature is disabled."
}
},
"summary": "Returns the authenticated user's basic identity claims.\r\nUsed by frontends in cookie-session mode to determine\r\n`isAuthenticated` without parsing the JWT (which is\r\nhttpOnly and invisible to JavaScript).",
"tags": [
"CookieSession"
]
}
},
"/api/v1/auth/session/revoke": {
"post": {
"responses": {
"204": {
"description": "Cookie session revoked."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Cookie session feature is disabled."
}
},
"summary": "Revokes the cookie session by clearing both cookies.",
"tags": [
"CookieSession"
]
}
},
"/api/v1/auth/step-up": {
"post": {
"description": "The token elevates the SESSION; the assertion authorises one irreversible\r\nOPERATION at a service that will not accept a bearer token it did not mint\r\n(debt-2026-08-19-008). Actions needing one also require\r\nEssence.Identity.Auth.Api.Controllers.InitiateStepUpRequest.PasswordHash: FR-15.008.7 demands password\r\nre-entry and a second factor, and the assertion attests to both.",
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/InitiateStepUpRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/InitiateStepUpRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/InitiateStepUpRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InitiateStepUpResponse"
}
}
},
"description": "OK"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Conflict"
},
"429": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Too Many Requests"
}
},
"summary": "Initiate a step-up challenge for a privileged action. On success returns a\r\nshort-lived `aal=2` step-up token, plus — for an irreversible action —\r\nthe signed assertion its consuming service re-verifies server-side.",
"tags": [
"StepUp"
]
}
},
"/api/v1/auth/step-up/email-code": {
"post": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/StepUpEmailCodeRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/StepUpEmailCodeRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/StepUpEmailCodeRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SendEmailOtpResult"
}
}
},
"description": "Outcome of the send (`sent` false with a `status` when declined, e.g. unverified email)."
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unknown action."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Email is not a step-up factor for this action on this account."
},
"429": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The hourly email-code allowance is spent."
}
},
"summary": "Email the one-time code a step-up for `action` will verify with\r\n`factor=email` (#8753). Unlike `POST /api/v1/mfa/send/email`, it\r\nserves an account whose MFA is off when the action's email floor applies —\r\nthe only way such an account can obtain a `password-change` elevation.",
"tags": [
"StepUp"
]
}
},
"/api/v1/auth/step-up/probate-grant": {
"post": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/InitiateProbateStepUpRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/InitiateProbateStepUpRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/InitiateProbateStepUpRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProbateStepUpResponse"
}
}
},
"description": "OK"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden"
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Conflict"
}
},
"summary": "Initiate a probate step-up. On success returns an `aal=2` step-up\r\ntoken recording the authority basis.",
"tags": [
"ProbateStepUp"
]
}
},
"/api/v1/auth/step-up/probate-grant/assurance": {
"get": {
"parameters": [
{
"in": "query",
"name": "estateId",
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProbateAssuranceResult"
}
}
},
"description": "OK"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
}
},
"summary": "Return the achieved-vs-required assurance for the current probate session\r\non an estate, for the release-gate surface.",
"tags": [
"ProbateStepUp"
]
}
},
"/api/v1/auth/step-up/probate-grant/challenge": {
"post": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/SendProbateStepUpChallengeRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/SendProbateStepUpChallengeRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/SendProbateStepUpChallengeRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProbateStepUpChallengeResponse"
}
}
},
"description": "OK"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
}
},
"summary": "Issue a probate step-up challenge for the chosen accessible factor.",
"tags": [
"ProbateStepUp"
]
}
},
"/api/v1/auth/step-up/required-factors": {
"get": {
"parameters": [
{
"in": "query",
"name": "action",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RequiredFactorsResponse"
}
}
},
"description": "OK"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
}
},
"summary": "Returns the step-up factors the calling session may use (intersection of\r\nthe user's enrolled factors and the deployment-allowed factor set). With\r\n`?action=`, the factors a step-up for THAT action will accept — which for\r\n`password-change` includes the email floor for an account with no other\r\nfactor (#8753). For `passkey-removal`, `contact-change` (GPG 44 medium,\r\nDVS-4.4) and `authenticator-enrolment` (DVS-4.4b) it never includes `email` or `backup-code`; an account with none of\r\nTOTP, SMS or a passkey is offered `password` instead.",
"tags": [
"StepUp"
]
}
},
"/api/v1/auth/takeover/emergency-freeze": {
"post": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/EmergencyFreezeRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/EmergencyFreezeRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/EmergencyFreezeRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EmergencyFreezeResponse"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/EmergencyFreezeResponse"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/EmergencyFreezeResponse"
}
}
},
"description": "OK"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
}
},
"summary": "Place an emergency credential freeze on the caller's own account and terminate every\r\nactive session. Idempotent: a repeat call returns the original freeze instant.",
"tags": [
"Takeover"
]
}
},
"/api/v1/auth/takeover/emergency-freeze/by-signed-link": {
"post": {
"description": "\n\r\n `[AllowAnonymous]` (SEC-002, explicit): the reader of an FR-66.114\r\n \"this wasn't me → freeze\" alert holds no device, no app and no session — that is the\r\n definition of the `account-recovery-lost-devices` population, and requiring a\r\n bearer token would make this control unexecutable by everyone it exists for. The HMAC\r\n over `(accountId . recoverySessionId . expiresAtUnix)` IS the credential.\r\n \r\n\n\r\n Rate-limited by IP under the platform default policy (SEC-004), which is what bounds\r\n signature guessing on an unauthenticated endpoint.\r\n \r\n\n\r\n A bad signature and an unknown account both answer 401, never 404 — the two\r\n must be indistinguishable or the endpoint becomes an account-existence oracle for\r\n anyone who can POST JSON. An expired link answers 410, which is safe to\r\n distinguish because it is only ever reached by a link that already proved genuine.\r\n ",
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/FreezeBySignedLinkRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/FreezeBySignedLinkRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/FreezeBySignedLinkRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FreezeBySignedLinkResponse"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/FreezeBySignedLinkResponse"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/FreezeBySignedLinkResponse"
}
}
},
"description": "OK"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"410": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Gone"
}
},
"summary": "Place an emergency credential freeze authorised by a signed link rather than a\r\nsession, and discard the in-flight recovery attempt the link names.",
"tags": [
"Takeover"
]
}
},
"/api/v1/auth/takeover/incident": {
"get": {
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TakeoverStateView"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/TakeoverStateView"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/TakeoverStateView"
}
}
},
"description": "OK"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
}
},
"summary": "The caller's own takeover-recovery state: whether the account is frozen right now, and\r\nthe open incident if there is one (#7393). The hub renders its step rail from this, so a\r\nvictim who leaves and comes back resumes instead of being offered the freeze again.",
"tags": [
"Takeover"
]
}
},
"/api/v1/auth/takeover/incident/{incidentId}/progress": {
"post": {
"parameters": [
{
"in": "path",
"name": "incidentId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/RecordTakeoverProgressRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/RecordTakeoverProgressRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/RecordTakeoverProgressRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TakeoverStateView"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/TakeoverStateView"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/TakeoverStateView"
}
}
},
"description": "OK"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
}
},
"summary": "Record a completed step (`keys-rotated`, `shares-revoked`, `closed`) on the\r\ncaller's own open incident (#7393). An incident id that is not the caller's open incident\r\nanswers 404 whether it belongs to someone else or to no one.",
"tags": [
"Takeover"
]
}
},
"/api/v1/auth/takeover/new-device-alert-freeze": {
"post": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/NewDeviceFreezeLinkRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/NewDeviceFreezeLinkRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/NewDeviceFreezeLinkRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NewDeviceFreezeLinkResponse"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/NewDeviceFreezeLinkResponse"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/NewDeviceFreezeLinkResponse"
}
}
},
"description": "The link was live: the account is frozen and every session revoked."
},
"410": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The link cannot be used — the same answer whatever the reason."
}
},
"summary": "Freeze the account a new-device alert's link was minted for, and sign out every device.",
"tags": [
"NewDeviceFreezeLink"
]
}
},
"/api/v1/auth/users/{userId}/unlock": {
"post": {
"parameters": [
{
"description": "User ID to unlock",
"in": "path",
"name": "userId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UnlockAccountResult"
}
}
},
"description": "Account unlocked successfully"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "User not found"
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Conflict"
}
},
"summary": "Unlocks a locked user account. Requires admin role.",
"tags": [
"Auth"
]
}
},
"/api/v1/auth/validate-token": {
"post": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/ValidateTokenQuery"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/ValidateTokenQuery"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ValidateTokenQuery"
}
}
},
"description": "Token validation request"
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TokenValidationDto"
}
}
},
"description": "Token validated successfully"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid request data"
}
},
"summary": "Validates an access token and returns user information.\r\nUsed for service-to-service authentication.",
"tags": [
"Auth"
]
}
},
"/api/v1/auth/verify-email": {
"get": {
"parameters": [
{
"description": "The single-use verification token from the email link.",
"in": "query",
"name": "token",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/VerifyEmailResult"
}
}
},
"description": "Email verified (or already verified)."
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Token missing, invalid, or expired."
}
},
"summary": "Verifies a user's email address from the link in the verification email.",
"tags": [
"Auth"
]
}
},
"/api/v1/auth/webauthn/authenticate/begin": {
"post": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/BeginWebAuthnAuthenticationRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/BeginWebAuthnAuthenticationRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/BeginWebAuthnAuthenticationRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebAuthnAuthenticationOptions"
}
}
},
"description": "Authentication options returned"
}
},
"summary": "Begins a WebAuthn authentication ceremony. Returns credential request options\r\nincluding a challenge for the client to pass to navigator.credentials.get().\r\nSupports both identified (user known) and discoverable (passkey) flows.",
"tags": [
"WebAuthn"
]
}
},
"/api/v1/auth/webauthn/authenticate/complete": {
"post": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/CompleteWebAuthnAuthenticationRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/CompleteWebAuthnAuthenticationRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/CompleteWebAuthnAuthenticationRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebAuthnAuthenticationResult"
}
}
},
"description": "Authentication successful, tokens returned"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Assertion verification failed"
}
},
"summary": "Completes a WebAuthn authentication ceremony. Verifies the assertion\r\nresponse and issues authentication tokens on success.",
"tags": [
"WebAuthn"
]
}
},
"/api/v1/auth/webauthn/credentials": {
"get": {
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebAuthnCredentialListResponse"
}
}
},
"description": "Enrolled passkeys returned."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "User not authenticated."
}
},
"summary": "Lists the calling user's active passkeys for the Security-settings\r\nmanagement surface. Returns an envelope `{ data: [...] }`.",
"tags": [
"WebAuthn"
]
}
},
"/api/v1/auth/webauthn/credentials/{id}": {
"delete": {
"description": "Requires a fresh (≤ 5 minutes) GPG 44 medium step-up elevation, `act=passkey-removal`, on\r\n`X-Step-Up-Token` (Essence.Identity.Auth.Api.Security.IPasskeyRemovalStepUpGate; DVS-4.4, TF 1.0 §7.3.1.c):\r\nremoving a way to sign in is not something a bearer session alone may do. Checked before the\r\ncredential is looked up, so a refusal says nothing about which passkeys exist.",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"204": {
"description": "Credential removed."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No acceptable step-up elevation (`step-up-required`, or `step-up-resource-mismatch`)."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Credential not found or not owned by the caller."
}
},
"summary": "Removes (deactivates) one of the calling user's passkeys.",
"tags": [
"WebAuthn"
]
},
"patch": {
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/RenameWebAuthnCredentialRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/RenameWebAuthnCredentialRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/RenameWebAuthnCredentialRequest"
}
}
}
},
"responses": {
"204": {
"description": "Credential renamed."
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid name."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Credential not found or not owned by the caller."
}
},
"summary": "Renames one of the calling user's passkeys.",
"tags": [
"WebAuthn"
]
}
},
"/api/v1/auth/webauthn/login/complete": {
"post": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/CompleteWebAuthnAuthenticationRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/CompleteWebAuthnAuthenticationRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/CompleteWebAuthnAuthenticationRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebAuthnAuthenticationResult"
}
}
},
"description": "Authentication successful, tokens returned"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Assertion verification failed"
}
},
"summary": "Completes a WebAuthn authentication ceremony. Verifies the assertion\r\nresponse and issues authentication tokens on success.",
"tags": [
"WebAuthn"
]
}
},
"/api/v1/auth/webauthn/login/options": {
"post": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/BeginWebAuthnAuthenticationRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/BeginWebAuthnAuthenticationRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/BeginWebAuthnAuthenticationRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebAuthnAuthenticationOptions"
}
}
},
"description": "Authentication options returned"
}
},
"summary": "Begins a WebAuthn authentication ceremony. Returns credential request options\r\nincluding a challenge for the client to pass to navigator.credentials.get().\r\nSupports both identified (user known) and discoverable (passkey) flows.",
"tags": [
"WebAuthn"
]
}
},
"/api/v1/auth/webauthn/passwordless/challenge": {
"post": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/PasswordlessLoginChallengeRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/PasswordlessLoginChallengeRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/PasswordlessLoginChallengeRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PasswordlessLoginChallengeResult"
}
}
},
"description": "Challenge issued"
}
},
"summary": "Issues a passwordless WebAuthn challenge with an EMPTY\r\n`allowCredentials` list so the authenticator picks a\r\ndiscoverable credential (passkey). No username is collected at\r\nthis step; the user is identified by the `userHandle` the\r\nauthenticator returns at login time.",
"tags": [
"WebAuthn"
]
}
},
"/api/v1/auth/webauthn/passwordless/login": {
"post": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/PasswordlessLoginRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/PasswordlessLoginRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/PasswordlessLoginRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PasswordlessLoginResult"
}
}
},
"description": "Login successful, tokens returned"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Verification failed"
}
},
"summary": "Completes a passwordless WebAuthn login by verifying the\r\nassertion against the credential identified by the supplied\r\n`userHandle`. On success returns full authentication\r\ntokens — this is a primary-factor login, no password involved.",
"tags": [
"WebAuthn"
]
}
},
"/api/v1/auth/webauthn/register/begin": {
"post": {
"description": "Requires a fresh (≤ 5 minutes) `act=authenticator-enrolment` elevation on\r\n`X-Step-Up-Token`, proved with a factor the account already has (DVS-4.4b): otherwise a\r\nbearer session alone could add its own passkey and then pass every other step-up with it.",
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/BeginWebAuthnRegistrationRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/BeginWebAuthnRegistrationRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/BeginWebAuthnRegistrationRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebAuthnRegistrationOptions"
}
}
},
"description": "Registration options returned"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "User not authenticated, or no acceptable step-up elevation (`step-up-required`)"
}
},
"summary": "Begins a WebAuthn registration ceremony. Returns credential creation options\r\nincluding a challenge for the client to pass to navigator.credentials.create().",
"tags": [
"WebAuthn"
]
}
},
"/api/v1/auth/webauthn/register/complete": {
"post": {
"description": "Requires the same fresh `act=authenticator-enrolment` elevation as `register/begin`\r\n(DVS-4.4b), so a ceremony begun with one cannot be finished after it has gone stale.",
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/CompleteWebAuthnRegistrationRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/CompleteWebAuthnRegistrationRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/CompleteWebAuthnRegistrationRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebAuthnRegistrationResult"
}
}
},
"description": "Credential registered successfully"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Attestation verification failed"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No acceptable step-up elevation (`step-up-required`)"
}
},
"summary": "Completes a WebAuthn registration ceremony. Verifies the attestation\r\nresponse from the authenticator and stores the credential.",
"tags": [
"WebAuthn"
]
}
},
"/api/v1/auth/webauthn/register/options": {
"post": {
"description": "Requires a fresh (≤ 5 minutes) `act=authenticator-enrolment` elevation on\r\n`X-Step-Up-Token`, proved with a factor the account already has (DVS-4.4b): otherwise a\r\nbearer session alone could add its own passkey and then pass every other step-up with it.",
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/BeginWebAuthnRegistrationRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/BeginWebAuthnRegistrationRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/BeginWebAuthnRegistrationRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebAuthnRegistrationOptions"
}
}
},
"description": "Registration options returned"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "User not authenticated, or no acceptable step-up elevation (`step-up-required`)"
}
},
"summary": "Begins a WebAuthn registration ceremony. Returns credential creation options\r\nincluding a challenge for the client to pass to navigator.credentials.create().",
"tags": [
"WebAuthn"
]
}
},
"/api/v1/biometric-reenrolment": {
"post": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/OpenBiometricReenrolmentRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/OpenBiometricReenrolmentRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/OpenBiometricReenrolmentRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BiometricReenrolmentResult"
}
}
},
"description": "The opened session (opaque reference + deep-link + coarse state)."
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No authenticated subject."
}
},
"summary": "Opens a re-enrolment session for the caller's biometric-mismatch lockout and raises the\r\nre-establishment-required alert. Reachable while locked out: a recovery-scoped step-up token\r\nis a validly-signed Essence JWT and passes the bearer scheme, exactly like a full session\r\n(mirrors Essence.Identity.Auth.Api.Controllers.TakeoverController). The subject is taken from the caller's own\r\n`sub` claim, and the org from the `organization_id` claim when present.",
"tags": [
"BiometricReenrolment"
]
}
},
"/api/v1/biometric-reenrolment/oversight": {
"get": {
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BiometricReenrolmentOversightResult"
}
}
},
"description": "The in-flight cohort (opaque member ref, coarse status, step, elapsed)."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The caller has no org context (not an org administrator)."
}
},
"summary": "The org oversight worklist: members of the caller's org whose biometric re-enrolment is\r\nin-progress / stalled. Scoped strictly to the caller's own `organization_id` claim, so\r\ncross-org reads are impossible by construction (no route org to forge).",
"tags": [
"BiometricReenrolment"
]
}
},
"/api/v1/biometric-reenrolment/{assuranceRef}/advance": {
"post": {
"parameters": [
{
"in": "path",
"name": "assuranceRef",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/StepRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/StepRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/StepRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BiometricReenrolmentResult"
}
}
},
"description": "The updated session state."
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No such session for this owner."
}
},
"summary": "Advances the caller's own in-flight session to a new coarse step.",
"tags": [
"BiometricReenrolment"
]
}
},
"/api/v1/biometric-reenrolment/{assuranceRef}/resolve": {
"post": {
"parameters": [
{
"in": "path",
"name": "assuranceRef",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/OutcomeRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/OutcomeRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/OutcomeRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BiometricReenrolmentResult"
}
}
},
"description": "The resolved session state."
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No such session for this owner."
}
},
"summary": "Resolves the caller's own session terminally — re-established or cancelled.",
"tags": [
"BiometricReenrolment"
]
}
},
"/api/v1/developer/support-access/agents": {
"get": {
"parameters": [
{
"in": "query",
"name": "appId",
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/SupportAgentDto"
},
"type": "array"
}
}
},
"description": "OK"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
},
"503": {
"description": "Service Unavailable"
}
},
"summary": "Every agent of the application, suspended ones included, oldest enrolment first. 404 when\r\nthe caller does not administer the application; 503 when the Developer Portal cannot be asked.",
"tags": [
"SupportAccessAgents"
]
},
"post": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/EnrolSupportAgentRequestBody"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/EnrolSupportAgentRequestBody"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/EnrolSupportAgentRequestBody"
}
}
}
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SupportAgentDto"
}
}
},
"description": "Created"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Conflict"
},
"503": {
"description": "Service Unavailable"
}
},
"summary": "Invite one address to be an agent: 201 with `status: invited` and no `principalId`,\r\nidentically whether or not the address has an Essence account (#21852). An address already\r\ninvited to or enrolled on the application is 409. 400 names a refused field; 404 / 503 as for\r\nthe list.",
"tags": [
"SupportAccessAgents"
]
}
},
"/api/v1/developer/support-access/agents/status": {
"post": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/SetSupportAgentStatusRequestBody"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/SetSupportAgentStatusRequestBody"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/SetSupportAgentStatusRequestBody"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SupportAgentStatusChangeDto"
}
}
},
"description": "OK"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
},
"503": {
"description": "Service Unavailable"
}
},
"summary": "Suspend or reinstate several agents at once, atomically. Every id must be an agent of the\r\napplication, or nothing changes (404 `support-agent-not-found`). `updated` counts\r\nthe agents whose status actually changed.",
"tags": [
"SupportAccessAgents"
]
}
},
"/api/v1/developer/support-access/policy": {
"get": {
"parameters": [
{
"in": "query",
"name": "appId",
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SupportImpersonationPolicyDto"
}
}
},
"description": "OK"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
},
"503": {
"description": "Service Unavailable"
}
},
"summary": "The application's policy. An application that has never saved one answers the closed\r\nposture (nobody may raise a request) with `configured: false`. 404 when the caller does\r\nnot administer the application; 503 when the Developer Portal cannot be asked.",
"tags": [
"SupportAccessPolicy"
]
},
"put": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/SupportImpersonationPolicyRequestBody"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/SupportImpersonationPolicyRequestBody"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/SupportImpersonationPolicyRequestBody"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SupportImpersonationPolicyDto"
}
}
},
"description": "OK"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
},
"503": {
"description": "Service Unavailable"
}
},
"summary": "Save (create or replace) the application's policy. Every field is replaced. 400 names the\r\nfield a value is refused for; 404 / 503 as for the read.",
"tags": [
"SupportAccessPolicy"
]
}
},
"/api/v1/developer/support-access/requests": {
"get": {
"parameters": [
{
"in": "query",
"name": "appId",
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"in": "query",
"name": "status",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "agentId",
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"in": "query",
"name": "cursor",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "pageSize",
"schema": {
"format": "int32",
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SupportAccessRequestListItemDtoCursorResult"
}
}
},
"description": "OK"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
},
"503": {
"description": "Service Unavailable"
}
},
"summary": "The application's requests, newest first, keyset-paginated (#21871). An administrator of the\r\napplication sees every request; an agent sees only its own. status and\r\nagentId narrow. 404 when the caller is neither an agent nor an\r\nadministrator of the application, or it does not exist; 503 when the Developer Portal cannot\r\nbe asked; 400 for a cursor this list did not issue.",
"tags": [
"SupportAccessRequests"
]
},
"post": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/RaiseSupportAccessRequestBody"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/RaiseSupportAccessRequestBody"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/RaiseSupportAccessRequestBody"
}
}
}
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SupportAccessRequestDto"
}
}
},
"description": "Created"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unprocessable Content"
},
"503": {
"description": "Service Unavailable"
}
},
"summary": "Raise a request. 201 with the request (`pending-supervisor` when the policy requires dual\r\napproval, else `pending-customer`); 422 `support-access-request-refused` with every\r\n`violations[]` entry when the policy refuses it, and nothing is recorded. 404 when the\r\ncaller is neither the named agent nor an administrator of the application; 503 when the\r\nDeveloper Portal cannot be asked.",
"tags": [
"SupportAccessRequests"
]
}
},
"/api/v1/developer/support-access/requests/mine": {
"get": {
"description": "A request still held for the partner's own supervisor is not listed — the customer has not\r\nbeen asked yet — nor is one past its 72-hour deadline, nor one already decided.",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/PendingSupportAccessRequestDto"
},
"type": "array"
}
}
},
"description": "OK"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
}
},
"summary": "The support-access requests awaiting the signed-in account holder's own decision, newest\r\nfirst. An empty array genuinely means none are pending.",
"tags": [
"SupportAccessSubjectDecision"
]
}
},
"/api/v1/developer/support-access/requests/mine/sessions": {
"get": {
"description": "\n\r\n Why this is here and not on the partner's list. The client used to read\r\n `GET …/requests?consentIds=…`, which is the partner-side list: scoped to an\r\n administrator of the application or an agent on its roster, and so unanswerable for the one\r\n audience that needs it — the customer whose account the session is over. The banner over a\r\n live session said \"A support agent\" with no company as a result. The subject's reads belong\r\n beside the subject's decision, under the capability the audience already holds.\r\n \r\n\n\r\n Carries no authority. No expiry, no status, no scopes — those are the EPIC 9 grant's,\r\n and ending the session works from the grant alone. A name that could not be resolved, or a\r\n descriptor read that failed outright, therefore cannot hide a live session or weaken its\r\n kill-switch.\r\n \r\n\n\r\n `consentIds` is a comma-separated list; ids naming no session of the caller's are simply\r\n absent from the answer, because answering an error for them would disclose which ids exist.\r\n An empty list is an empty array, not an error.\r\n ",
"parameters": [
{
"in": "query",
"name": "consentIds",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/SupportAccessSessionDescriptorDto"
},
"type": "array"
}
}
},
"description": "One row per consent id that names a session over the caller's own account."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
}
},
"summary": "The descriptive half of the support sessions over the caller's own account (#22084) — who is\r\nin the account, for which company, against which ticket — keyed by the consent ids of the\r\ngrants they themselves issued.",
"tags": [
"SupportAccessSubjectDecision"
]
}
},
"/api/v1/developer/support-access/requests/{requestId}/approve": {
"post": {
"parameters": [
{
"in": "path",
"name": "requestId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SupportAccessRequestListItemDto"
}
}
},
"description": "OK"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Conflict"
}
},
"summary": "A supervisor approves a request held `pending-supervisor`; it becomes\r\n`pending-customer` (#21869). 200 with the request; 404 when it does not exist or the caller\r\nis not on its application's roster; 403 `support-access-supervisor-not-eligible` with a\r\n`code` when the caller may not decide it; 409 when it is not awaiting a supervisor.",
"tags": [
"SupportAccessRequests"
]
}
},
"/api/v1/developer/support-access/requests/{requestId}/decision": {
"post": {
"description": "`grantId` is optional and, when sent, is verified rather than trusted: a client that\r\n created the grant itself (as the browser client does) names it, and a value that is not the\r\n grant this request's consent binds is `409`.",
"parameters": [
{
"in": "path",
"name": "requestId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/SupportAccessDecisionBody"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/SupportAccessDecisionBody"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/SupportAccessDecisionBody"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SupportAccessCustomerDecisionDto"
}
}
},
"description": "The decision, with the consent id and — for an approval — the grant and its expiry."
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Neither `allow` nor `deny`."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The request is not awaiting this caller's decision — one answer for decided, lapsed, held for a supervisor, and not theirs."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "A `grantId` that is not the grant this request's consent binds."
}
},
"summary": "Answer a request. `decision: \"allow\"` creates the time-boxed\r\n`support-impersonation` grant over the caller's own account and records it on the\r\nrequest; `decision: \"deny\"` ends the request and creates nothing.",
"tags": [
"SupportAccessSubjectDecision"
]
}
},
"/api/v1/developer/support-access/requests/{requestId}/decline": {
"post": {
"parameters": [
{
"in": "path",
"name": "requestId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/DeclineSupportAccessRequestBody"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeclineSupportAccessRequestBody"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/DeclineSupportAccessRequestBody"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SupportAccessRequestListItemDto"
}
}
},
"description": "OK"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Conflict"
}
},
"summary": "A supervisor declines a request held `pending-supervisor`, naming one of the decline\r\nreasons; it ends `declined` and the customer is never asked (#21869). Answers as\r\nM:Essence.Identity.Auth.Api.Controllers.SupportAccessRequestsController.Approve(System.Guid,System.Threading.CancellationToken); 400 for a reason that is not one of the decline reasons.",
"tags": [
"SupportAccessRequests"
]
}
},
"/api/v1/developer/support-access/sessions": {
"get": {
"parameters": [
{
"in": "query",
"name": "appId",
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"in": "query",
"name": "agentId",
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"in": "query",
"name": "subject",
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"in": "query",
"name": "from",
"schema": {
"format": "date-time",
"type": "string"
}
},
{
"in": "query",
"name": "to",
"schema": {
"format": "date-time",
"type": "string"
}
},
{
"in": "query",
"name": "cursor",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "limit",
"schema": {
"default": 100,
"format": "int32",
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/PartnerSupportSessionDto"
},
"type": "array"
}
}
},
"description": "OK"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
},
"503": {
"description": "Service Unavailable"
}
},
"summary": "One page of the application's support-access sessions, newest first, as a JSON array (the\r\nshape the console reads). When there are more, the next page's cursor is in\r\n`X-Next-Cursor`; pass it back as `cursor`. `from`/`to` bound when the\r\nsession was granted, `[from, to)`. An application the caller does not administer is\r\nthe same 404 as an unknown one; 503 when the Developer Portal cannot be asked.",
"tags": [
"SupportAccessOversight"
]
}
},
"/api/v1/developer/support-access/sessions/export.csv": {
"get": {
"parameters": [
{
"in": "query",
"name": "appId",
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"in": "query",
"name": "agentId",
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"in": "query",
"name": "subject",
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"in": "query",
"name": "from",
"schema": {
"format": "date-time",
"type": "string"
}
},
{
"in": "query",
"name": "to",
"schema": {
"format": "date-time",
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unprocessable Content"
},
"503": {
"description": "Service Unavailable"
}
},
"summary": "Every session matching the filters as CSV — the partner's own audit pack. Refused (422)\r\nrather than truncated when it would exceed Essence.Identity.Auth.Application.Queries.DelegateAccess.ExportPartnerSupportSessionsQuery.MaxRows.",
"tags": [
"SupportAccessOversight"
]
}
},
"/api/v1/developer/support-access/sessions/{id}/terminate": {
"post": {
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/TerminateSupportAccessSessionRequestBody"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/TerminateSupportAccessSessionRequestBody"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/TerminateSupportAccessSessionRequestBody"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TerminateSupportAccessSessionResult"
}
}
},
"description": "OK"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
},
"503": {
"description": "Service Unavailable"
}
},
"summary": "Force-terminate a support-access session of an application the caller administers. A\r\nsession that does not exist, is not a support session, or belongs to an application the\r\ncaller does not administer is the same 404. 503 when the Developer Portal cannot be asked\r\nwho administers the application.",
"tags": [
"SupportAccessSessions"
]
}
},
"/api/v1/devices": {
"get": {
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/DeviceDto"
},
"type": "array"
}
},
"text/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/DeviceDto"
},
"type": "array"
}
},
"text/plain": {
"schema": {
"items": {
"$ref": "#/components/schemas/DeviceDto"
},
"type": "array"
}
}
},
"description": "OK"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
}
},
"summary": "Get all devices for the authenticated user",
"tags": [
"Devices"
]
}
},
"/api/v1/devices/{id}": {
"delete": {
"description": "Requires a step-up elevation on `X-Step-Up-Token`\r\n(Essence.Identity.Auth.Api.Security.IDeviceRevocationStepUpGate, #8641): the revoke is\r\nirreversible, so a live session is not sufficient authority for it.",
"parameters": [
{
"description": "Device ID",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"description": "The FR-01.049 re-keying choice the account holder made (debt-2026-06-18-331,\r\njourney `lost-device-revocation-and-session-hygiene`). `false` — the\r\nsecure default, \"Rotate my keys now\". `true` — the user explicitly chose\r\n\"Lock out later\" and acknowledged the residual-access window, so the deferral and\r\nthe window they accepted are recorded on the audit-anchored\r\n`DeviceRemovedEvent` (`RekeyAction == \"deferred-warned\"`) instead.\r\n\n\r\nThe SPA (`multiDeviceSyncApi.removeDevice`) has always appended\r\n`?deferRotation=true` for the deferred path, but this action bound no such\r\nparameter, so the user's consent decision about their own device security was\r\ndiscarded while the dialog reported success and promised \"this choice is recorded\r\nin your activity log\". Binding it here keeps that promise, and matches\r\nMultiDeviceSync's `DevicesController.RemoveDevice` on the sibling path.\r\n",
"in": "query",
"name": "deferRotation",
"schema": {
"default": false,
"type": "boolean"
}
},
{
"description": "Why the owner is removing the device (FR-01.049, #11394): `user-initiated`\r\n(the default), `lost` or `stolen`. Recorded on the audit-anchored\r\n`DeviceRemovedEvent.Reason`; any other value is refused 400.",
"in": "query",
"name": "reason",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeleteDeviceResult"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/DeleteDeviceResult"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/DeleteDeviceResult"
}
}
},
"description": "OK"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
}
},
"summary": "Delete a device and revoke all its sessions",
"tags": [
"Devices"
]
},
"get": {
"parameters": [
{
"description": "Device ID",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeviceDto"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/DeviceDto"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/DeviceDto"
}
}
},
"description": "OK"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
}
},
"summary": "Get a specific device by ID",
"tags": [
"Devices"
]
}
},
"/api/v1/devices/{id}/block": {
"post": {
"parameters": [
{
"description": "Device ID",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/BlockDeviceRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/BlockDeviceRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/BlockDeviceRequest"
}
}
},
"description": "Block request with reason"
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BlockDeviceResult"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/BlockDeviceResult"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/BlockDeviceResult"
}
}
},
"description": "OK"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
}
},
"summary": "Block a device (suspicious activity or user-initiated)",
"tags": [
"Devices"
]
}
},
"/api/v1/devices/{id}/name": {
"put": {
"parameters": [
{
"description": "Device ID",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/UpdateDeviceNameRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateDeviceNameRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/UpdateDeviceNameRequest"
}
}
},
"description": "Update request with new name"
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateDeviceNameResult"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/UpdateDeviceNameResult"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/UpdateDeviceNameResult"
}
}
},
"description": "OK"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
}
},
"summary": "Update the friendly name of a device",
"tags": [
"Devices"
]
}
},
"/api/v1/devices/{id}/trust": {
"post": {
"description": "Requires a fresh (≤ 5 minutes) `act=recovery-settings-change` elevation on\r\n`X-Step-Up-Token` (DVS-4.4c): a trusted device skips new-device verification and can approve\r\nother devices' sign-ins, so marking one trusted changes how the account can be got back into.",
"parameters": [
{
"description": "Device ID",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TrustDeviceResult"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/TrustDeviceResult"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/TrustDeviceResult"
}
}
},
"description": "OK"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Conflict"
}
},
"summary": "Trust a device (\"Remember this device\" functionality)",
"tags": [
"Devices"
]
}
},
"/api/v1/identity/adulthood-handover/claim-context": {
"get": {
"parameters": [
{
"in": "query",
"name": "guardianshipId",
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ClaimVaultContextDto"
}
}
},
"description": "OK"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
}
},
"summary": "Read the claim-context (\"what you keep / what changes\"). Seam: `getClaimContext`.",
"tags": [
"AdulthoodHandover"
]
}
},
"/api/v1/identity/adulthood-handover/handover-confirmation": {
"get": {
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HandoverConfirmationDto"
}
}
},
"description": "OK"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
}
},
"summary": "Read the verified-majority handover confirmation: the live who-has-access set + the\r\nrevocation date. Seam: `getHandoverConfirmation`.",
"tags": [
"AdulthoodHandover"
]
}
},
"/api/v1/identity/adulthood-handover/key-claim/rekey-token": {
"post": {
"description": "\n\r\n Authorisation. Requires an authenticated caller (class-level\r\n `[Authorize]`; no policy name, so nothing can 500 on an unregistered policy). The\r\n subject is taken from the caller's OWN claims via `GetUserIdFromClaims()` — there is\r\n deliberately no `{childId}`-style route or body parameter, so a guardian holding a\r\n perfectly valid session cannot request a key-custody token for the young adult: they would\r\n only ever mint one bound to their own (non-existent) majority claim and get a 404.\r\n\n\r\n Status codes. 404 when the caller has no majority claim (identical to the\r\n absent-record 404 elsewhere on this controller, so claim existence cannot be probed);\r\n 403 when the claim exists but is not yet `Verified` — the authority does not\r\n exist yet, which is a permission answer rather than the state-conflict 409 used for\r\n mis-sequenced challenge operations; 409 when a token was already issued (one shot).\r\n\n\r\n Zero-knowledge. The token authorises a re-wrap performed on the device. It\r\n carries only opaque identifiers; no key material passes through this endpoint.",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IssueMajorityTransitionRekeyTokenResult"
}
}
},
"description": "OK"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Conflict"
}
},
"summary": "Mint the one-shot, 5-minute `purpose=majority-transition-rekey` token the\r\nnow-adult presents to EPIC 1's `POST /api/v1/keys/wrapped-umk/majority-transition-rekey`\r\nto re-wrap their vault UMK under their own KEK (decision D-439, FR-30.011 / CC-070).",
"tags": [
"AdulthoodHandover"
]
}
},
"/api/v1/identity/adulthood-handover/key-claim/resend": {
"post": {
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ResendKeyClaimCodeResult"
}
}
},
"description": "OK"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Conflict"
}
},
"summary": "Resend the one-time code (rotates the code, no expiry). Seam: `resendKeyClaimCode`.",
"tags": [
"AdulthoodHandover"
]
}
},
"/api/v1/identity/adulthood-handover/key-claim/start": {
"post": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/StartKeyClaimRequestBody"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/StartKeyClaimRequestBody"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/StartKeyClaimRequestBody"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StartKeyClaimResult"
}
}
},
"description": "OK"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
}
},
"summary": "Start the key-claim ceremony: issue a one-time-code identity-verification challenge\r\n(AAL2, no expiry). Seam: `startKeyClaim` (aka `verify/start`).",
"tags": [
"AdulthoodHandover"
]
}
},
"/api/v1/identity/adulthood-handover/key-claim/verify": {
"post": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/VerifyKeyClaimRequestBody"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/VerifyKeyClaimRequestBody"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/VerifyKeyClaimRequestBody"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/VerifyKeyClaimResult"
}
}
},
"description": "OK"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Conflict"
}
},
"summary": "Verify the submitted one-time code and, on success, re-wrap the vault UMK to the now-adult\r\nand record the minor→adult identity change + revocation proof. Seam: `verifyKeyClaim`\r\n(aka `verify/submit`). Returns `200` with `verified=false` on a code\r\nmismatch (with remaining attempts), so the client can prompt a retry.",
"tags": [
"AdulthoodHandover"
]
}
},
"/api/v1/identity/agents": {
"get": {
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/DelegatedAgentDto"
},
"type": "array"
}
}
},
"description": "OK"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
}
},
"summary": "Lists the caller's own agents and their containment state.",
"tags": [
"DelegatedAgents"
]
},
"post": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/RegisterDelegatedAgentRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/RegisterDelegatedAgentRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/RegisterDelegatedAgentRequest"
}
}
}
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RegisterDelegatedAgentResponse"
}
}
},
"description": "Created"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
}
},
"summary": "Registers an AI agent to act on the caller's behalf. The credential secret is in the\r\nresponse body and is never retrievable again — only its hash is stored.",
"tags": [
"DelegatedAgents"
]
}
},
"/api/v1/identity/agents/token": {
"post": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/AgentTokenRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/AgentTokenRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/AgentTokenRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AgentTokenResponse"
}
}
},
"description": "OK"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
}
},
"summary": "Exchanges an agent credential for a short-lived agent session. Anonymous because the\r\ncredential IS the authentication — an agent has no prior session to present.",
"tags": [
"DelegatedAgents"
]
}
},
"/api/v1/identity/agents/{agentReference}/key": {
"put": {
"parameters": [
{
"in": "path",
"name": "agentReference",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/AgentPublicJwkRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/AgentPublicJwkRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/AgentPublicJwkRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AgentKeyResponse"
}
}
},
"description": "OK"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Conflict"
}
},
"summary": "Registers — or replaces — the agent's EC P-256 public key (agent-gateway CONTRACTS §1).\r\nThe body is one public JWK with exactly `kty`, `crv`, `x` and `y`; a\r\nJWK carrying private material (`d`) or any other member, key type or curve is refused\r\n400. Once registered, every access token the agent is issued carries\r\n`cnf.jkt` = the key's RFC 7638 thumbprint, binding it to proof of possession.\r\n \r\n\nCallable only by the agent's own principal. An agent cannot set its own key: its\r\ntoken's `sub` is its reference, not a user id, so it never resolves to a caller.",
"tags": [
"DelegatedAgents"
]
}
},
"/api/v1/identity/agents/{agentReference}/suspend": {
"post": {
"parameters": [
{
"in": "path",
"name": "agentReference",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/SuspendDelegatedAgentRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/SuspendDelegatedAgentRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/SuspendDelegatedAgentRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SuspendDelegatedAgentResponse"
}
}
},
"description": "OK"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
}
},
"summary": "Cuts an agent's credential and every live session it holds, for a named EPIC 12 incident,\r\nand returns the suspension reference the containment chain records.\r\n \r\n\nCallable by the agent's own principal (cutting off their own agent) or by an\r\nincident responder. Idempotent: a retried containment leg returns the same suspension\r\nreference rather than minting a second suspension.",
"tags": [
"DelegatedAgents"
]
}
},
"/api/v1/identity/assist/actions": {
"post": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/RecordAssistActionRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/RecordAssistActionRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/RecordAssistActionRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RecordAssistActionResponse"
}
}
},
"description": "OK"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Conflict"
}
},
"summary": "Record a delegate-attributed assist action against an active session. The\r\nhelper is always the authenticated caller (audit attribution). Returns\r\n`409` when the session has no active grant or is held by a different\r\nhelper.",
"tags": [
"Assist"
]
}
},
"/api/v1/identity/assist/consent": {
"post": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/ConsentToAssistRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConsentToAssistRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ConsentToAssistRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConsentToAssistResponse"
}
}
},
"description": "OK"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden"
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Conflict"
}
},
"summary": "Record a live account owner's consent to be assisted at first-run. The\r\ngranter (oversight attribution) defaults to the authenticated caller — the\r\nconsenting owner. Idempotent: the same owner re-consenting for the same helper\r\non a live session returns `200` with the existing grant id; a session id\r\nthat carries any other grant returns `409 assist-session-taken`.",
"tags": [
"Assist"
]
}
},
"/api/v1/identity/assist/non-custody-attestation/{sessionId}": {
"get": {
"parameters": [
{
"in": "path",
"name": "sessionId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NonCustodyAttestationDto"
}
}
},
"description": "OK"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
}
},
"summary": "Read the verifiable non-custody attestation for an assist session — the\r\noversight-status read that proves the helper never accessed the owner's key\r\nor recovery material. Degrades honestly (`nonCustodyAttested=false`) if\r\nany breach was ever recorded.",
"tags": [
"Assist"
]
}
},
"/api/v1/identity/assist/sessions/{sessionId}/actions": {
"get": {
"parameters": [
{
"in": "path",
"name": "sessionId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/AssistActionDto"
},
"type": "array"
}
}
},
"description": "OK"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
}
},
"summary": "List the delegate-attributed action records for an assist session (the\r\noversight-status action feed).",
"tags": [
"Assist"
]
}
},
"/api/v1/identity/assist/{grantId}/revoke": {
"post": {
"parameters": [
{
"in": "path",
"name": "grantId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/RevokeAssistRequestBody"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/RevokeAssistRequestBody"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/RevokeAssistRequestBody"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RevokeAssistResult"
}
}
},
"description": "OK"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
}
},
"summary": "Revoke a consent-to-assist grant (clean teardown — \"assistance ended\").",
"tags": [
"Assist"
]
}
},
"/api/v1/identity/assurance": {
"get": {
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AssuranceRecordResult"
}
}
},
"description": "OK"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
}
},
"summary": "Reads the full authoritative assurance record, or 404 when none exists yet.",
"tags": [
"IdentityAssurance"
]
}
},
"/api/v1/identity/assurance/community-vouched": {
"get": {
"parameters": [
{
"in": "query",
"name": "limit",
"schema": {
"format": "int32",
"type": "integer"
}
},
{
"in": "query",
"name": "expiringWithinDays",
"schema": {
"format": "int32",
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CommunityVouchedAccountsResult"
}
}
},
"description": "OK"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden"
}
},
"summary": "Lists accounts whose identity assurance rests on community vouching, with the level\r\nthey hold and whether their assurance is current, expiring or stale — the oversight\r\nworklist for journey `community-vouching-onboarding-no-id`\r\n(debt-2026-06-06-143, and the admin half of debt-2026-06-06-140).\r\n \r\n\n\r\nAdmin-scoped: this is a cross-account view, so it is gated on the platform-admin policy\r\nrather than on the caller being the subject. It returns no name, no email and no evidence\r\n— a level, a provenance, two instants and an opaque anchor reference per row.\r\n\n\r\nThe attester chain (who vouched, from which organisation, and the anti-collusion\r\nverdict on the set) is EPIC 36's evidence and is deliberately not served here; the\r\noversight surface reads it from EPIC 36 and says so when it is unavailable.\r\n",
"tags": [
"IdentityAssurance"
]
}
},
"/api/v1/identity/assurance/policy": {
"get": {
"parameters": [
{
"in": "query",
"name": "invitedByOrg",
"schema": {
"type": "boolean"
}
},
{
"in": "query",
"name": "orgName",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProofingPolicyResult"
}
}
},
"description": "OK"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
}
},
"summary": "Returns the authoritative proofing policy for the authenticated account,\r\nor the documented per-actor default (`isDefault=true`) when none is\r\nrecorded yet. Capability (b).",
"tags": [
"IdentityAssurance"
]
}
},
"/api/v1/identity/assurance/proofing": {
"post": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/InitiateProofingRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/InitiateProofingRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/InitiateProofingRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProofingSessionResult"
}
}
},
"description": "OK"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
}
},
"summary": "Initiates an identity-proofing session for the authenticated account and\r\nreturns it (an existing live session is returned rather than duplicated).\r\nCapability (c).",
"tags": [
"IdentityAssurance"
]
}
},
"/api/v1/identity/assurance/proofing/{sessionId}/complete": {
"post": {
"parameters": [
{
"in": "path",
"name": "sessionId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/CompleteProofingRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/CompleteProofingRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/CompleteProofingRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProofingSessionResult"
}
}
},
"description": "OK"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
}
},
"summary": "Records the subject-reported outcome of their own proofing session.\r\n\n\r\nThis endpoint can only record a non-success outcome (failure/abandonment).\r\nA successful proofing lifts the account's authoritative assurance level,\r\nso it must be adjudicated by the proofing provider — the subject cannot\r\nassert their own success. Attempting to do so returns 403.\r\n",
"tags": [
"IdentityAssurance"
]
}
},
"/api/v1/identity/assurance/record": {
"post": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/RecordAssuranceRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/RecordAssuranceRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/RecordAssuranceRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AssuranceRecordResult"
}
}
},
"description": "OK"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden"
}
},
"summary": "Records the identity assurance level the authenticated account has reached\r\nat first-run as the authoritative EPIC 9 record, establishing its proofing\r\npolicy. Idempotent upsert. Capability (a)+(b).",
"tags": [
"IdentityAssurance"
]
}
},
"/api/v1/identity/assurance/recovery-decision": {
"post": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/RecordRecoveryDecisionRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/RecordRecoveryDecisionRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/RecordRecoveryDecisionRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AssuranceRecordResult"
}
}
},
"description": "OK"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
}
},
"summary": "Records the account holder's first-run recovery decision (recovery set up vs deferred)\r\non the authoritative assurance record so the compliance-evidence view can retrieve /\r\nfilter / export it from the authoritative EPIC 9 store (debt-2026-07-09-022). Returns\r\nthe updated record; 404 when no assurance record has been recorded yet.",
"tags": [
"IdentityAssurance"
]
}
},
"/api/v1/identity/attestations/contact": {
"get": {
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/ContactFieldAttestationDto"
},
"type": "array"
}
}
},
"description": "OK"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
}
},
"summary": "Lists every contact-field provenance attestation for the authenticated subject so the\r\npresent primitive can stamp each outbound field in one call.",
"tags": [
"FieldAttestations"
]
},
"post": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/AttestContactFieldRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/AttestContactFieldRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/AttestContactFieldRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FieldAttestationResult"
}
}
},
"description": "OK"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
}
},
"summary": "Records (or refreshes) a contact-field provenance attestation for the authenticated subject.\r\nSeam: `contactAttestationApi.attest` (debt-2026-07-03-216).",
"tags": [
"FieldAttestations"
]
}
},
"/api/v1/identity/attestations/contact/{fieldKey}": {
"get": {
"parameters": [
{
"in": "path",
"name": "fieldKey",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ContactFieldAttestationDto"
}
}
},
"description": "OK"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
}
},
"summary": "Reads the provenance attestation for one presented contact field of the authenticated\r\nsubject. Seam: `contactAttestationApi.get` (debt-2026-07-03-216).",
"tags": [
"FieldAttestations"
]
}
},
"/api/v1/identity/attestations/professional": {
"post": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/AttestProfessionalCredentialRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/AttestProfessionalCredentialRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/AttestProfessionalCredentialRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FieldAttestationResult"
}
}
},
"description": "OK"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
}
},
"summary": "Records (or refreshes) a professional-credential attestation for the authenticated subject.\r\nSeam: `professionalAttestationApi.attest` (debt-2026-07-04-024).",
"tags": [
"FieldAttestations"
]
}
},
"/api/v1/identity/attestations/professional/{fieldKey}": {
"get": {
"parameters": [
{
"in": "path",
"name": "fieldKey",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProfessionalAttestationDto"
}
}
},
"description": "OK"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
}
},
"summary": "Reads the professional-body attestation metadata for one listing field of the authenticated\r\nsubject. Seam: `professionalAttestationApi.get` (debt-2026-07-04-024).",
"tags": [
"FieldAttestations"
]
}
},
"/api/v1/identity/custodial-establishment-policy": {
"get": {
"parameters": [
{
"description": "ISO-3166 alpha-2 code.",
"in": "query",
"name": "jurisdiction",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CustodialPolicyResult"
}
}
},
"description": "OK"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
}
},
"summary": "Read the policy governing a jurisdiction.",
"tags": [
"CustodialEstablishmentPolicy"
]
}
},
"/api/v1/identity/custodial-orders": {
"get": {
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/CustodialOrderResult"
},
"type": "array"
}
}
},
"description": "OK"
}
},
"summary": "List the caller's own submitted custodial orders, most recent first.",
"tags": [
"CustodialOrders"
]
},
"post": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/SubmitCustodialOrderRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/SubmitCustodialOrderRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/SubmitCustodialOrderRequest"
}
}
}
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CustodialOrderResult"
}
}
},
"description": "Created"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
}
},
"summary": "Submit a custodial order for verification.",
"tags": [
"CustodialOrders"
]
}
},
"/api/v1/identity/custodial-orders/pending": {
"get": {
"parameters": [
{
"in": "query",
"name": "jurisdiction",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "cursor",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "pageSize",
"schema": {
"format": "int32",
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PendingCustodialOrderItemCursorResult"
}
}
},
"description": "OK"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden"
}
},
"summary": "The identity-authority queue: pending orders awaiting a recorded decision, oldest\r\nfirst (#13747). Every read is audited — who looked, not only who decided — because\r\nthe list enumerates children subject to live custodial proceedings. The role spans\r\nevery jurisdiction; jurisdiction can only narrow it.",
"tags": [
"CustodialOrders"
]
}
},
"/api/v1/identity/custodial-orders/{orderId}": {
"get": {
"parameters": [
{
"in": "path",
"name": "orderId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CustodialOrderResult"
}
}
},
"description": "OK"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
}
},
"summary": "Read a custodial order's verification state.",
"tags": [
"CustodialOrders"
]
}
},
"/api/v1/identity/custodial-orders/{orderId}/child-identity": {
"post": {
"parameters": [
{
"in": "path",
"name": "orderId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/ProvisionChildIdentityRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProvisionChildIdentityRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProvisionChildIdentityRequest"
}
}
}
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProvisionChildIdentityResult"
}
}
},
"description": "Created"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Conflict"
}
},
"summary": "Provision the child's new legal identity under this verified order\r\n(debt-2026-08-13-220). The new principal carries no attribute, alias or key\r\nderived from the pre-adoption identity.",
"tags": [
"CustodialOrders"
]
}
},
"/api/v1/identity/custodial-orders/{orderId}/decision": {
"post": {
"parameters": [
{
"in": "path",
"name": "orderId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/DecideCustodialOrderRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/DecideCustodialOrderRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/DecideCustodialOrderRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CustodialOrderResult"
}
}
},
"description": "OK"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Conflict"
}
},
"summary": "Record, as a platform operator, the decision the external authority made on a\r\npending order. Restricted to identity-authority callers. The verdict is stored as\r\noperator-transcribed (#13747) — the operator did not decide, the authority did.",
"tags": [
"CustodialOrders"
]
}
},
"/api/v1/identity/delegate-access/grants": {
"get": {
"parameters": [
{
"in": "query",
"name": "role",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/DelegateAccessGrantDto"
},
"type": "array"
}
}
},
"description": "OK"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
}
},
"summary": "List delegate-access grants. `role=principal` (default) lists the\r\ngrants the caller has issued (\"who can act for me\"); `role=delegate`\r\nlists the grants the caller holds (the \"Act as\" selector).",
"tags": [
"DelegateAccess"
]
},
"post": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/GrantDelegateAccessRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/GrantDelegateAccessRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/GrantDelegateAccessRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DelegateAccessGrantCreatedResponse"
}
}
},
"description": "OK"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden"
}
},
"summary": "Grant delegate access to an assistant / helper. The principal (the account\r\nowner delegating) is, by default, the authenticated caller. Idempotent:\r\nre-granting for the same delegate + delegation returns `200` with the\r\nexisting grant id (never a duplicate).",
"tags": [
"DelegateAccess"
]
}
},
"/api/v1/identity/delegate-access/grants/organisation": {
"get": {
"parameters": [
{
"in": "query",
"name": "cursor",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "pageSize",
"schema": {
"format": "int32",
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OrganisationDelegateAccessPairDtoCursorResult"
}
}
},
"description": "One page of the roster; an empty page is a true empty state."
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The cursor is not one this roster issued."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not an administrator, no org claim, or a contradicting org header."
}
},
"summary": "Every principal↔delegate pair in the caller's organisation, one keyset page at a time\r\n(#14066, debt-2026-08-11-791) — the exec office's roster: one assistant covering four\r\nexecutives, an executive's primary and holiday cover, a leaver whose every delegation\r\nmust end. Ending a pair stays the per-grant revoke, so each keeps its own closure record.\r\n\n\r\nOrganisation administrators only (`OrgOwner` / `OrgAdmin`). The organisation is\r\nbound from the caller's org claim; there is no parameter naming it, and an\r\n`X-Organization-Id` header that names a different one is refused rather than ignored.\r\n",
"tags": [
"DelegateAccess"
]
}
},
"/api/v1/identity/delegate-access/grants/{id}/revoke": {
"post": {
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/RevokeDelegateAccessRequestBody"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/RevokeDelegateAccessRequestBody"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/RevokeDelegateAccessRequestBody"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RevokeDelegateAccessResult"
}
}
},
"description": "OK"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
}
},
"summary": "Revoke a delegate-access grant (clean teardown of the acting-as authority). Only the\r\nprincipal, the delegate, the issuer, or an administrator of an organisation both parties\r\nbelong to may revoke; anyone else gets the same 404 as for an unknown id (#20297).",
"tags": [
"DelegateAccess"
]
}
},
"/api/v1/identity/delegate-access/sessions": {
"post": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/EstablishActingAsSessionRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/EstablishActingAsSessionRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/EstablishActingAsSessionRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EstablishActingAsSessionResult"
}
}
},
"description": "OK"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden"
}
},
"summary": "Establish a scoped acting-as session (the \"Act as [Principal]\" selection).\r\nThe caller must be the grant's own delegate and the grant must be active.\r\nReturns a short-lived delegated-session token plus the acting-as bar context.",
"tags": [
"DelegateAccess"
]
}
},
"/api/v1/identity/delegate-access/sessions/context": {
"get": {
"parameters": [
{
"in": "query",
"name": "grantId",
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ActingAsContextDto"
}
}
},
"description": "OK"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
}
},
"summary": "Read the live acting-as context the persistent \"Acting as [Principal]\" bar\r\nrenders from. Only the grant's own delegate can read it; it degrades the\r\ninstant the grant is revoked or expires (`isActive=false`).",
"tags": [
"DelegateAccess"
]
}
},
"/api/v1/identity/guardianships": {
"post": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/EstablishGuardianshipRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/EstablishGuardianshipRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/EstablishGuardianshipRequest"
}
}
}
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GuardianshipResultDto"
}
}
},
"description": "The guardianship was established."
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Missing/invalid fields, or the primary-guardian invariant is violated."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden"
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Conflict"
}
},
"summary": "Establishes a named guardianship over a supervised minor (Step 1 of the wizard).",
"tags": [
"Guardianships"
]
}
},
"/api/v1/identity/guardianships/{childId}/guardians": {
"get": {
"parameters": [
{
"in": "path",
"name": "childId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GuardianRosterDto"
}
}
},
"description": "The guardian roster."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No guardianship for this minor that the caller holds an active seat on\r\n (the same answer for \"not yours\" and \"does not exist\", #19329)."
}
},
"summary": "Returns the current guardian roster for a supervised minor (per-child console).",
"tags": [
"Guardianships"
]
},
"post": {
"parameters": [
{
"in": "path",
"name": "childId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/GuardianLinkDto"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/GuardianLinkDto"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/GuardianLinkDto"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GuardianRosterDto"
}
}
},
"description": "The updated guardian roster."
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid role/relationship, a duplicate guardian, or a transitioned guardianship."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No guardianship for this minor."
}
},
"summary": "Adds a scoped secondary guardian (co-guardian / successor-guardian / delegated-care-manager)\r\nto an active guardianship. A successor is added inactive (standby) until activated.",
"tags": [
"Guardianships"
]
}
},
"/api/v1/identity/guardianships/{childId}/guardians/{guardianId}": {
"delete": {
"parameters": [
{
"in": "path",
"name": "childId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"in": "path",
"name": "guardianId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GuardianRosterDto"
}
}
},
"description": "The updated guardian roster."
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The seat is the primary guardian, not found, or the guardianship has transitioned."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No guardianship for this minor."
}
},
"summary": "Removes a secondary guardian seat (the primary guardian can never be removed).",
"tags": [
"Guardianships"
]
}
},
"/api/v1/identity/guardianships/{childId}/guardians/{guardianId}/activate": {
"post": {
"parameters": [
{
"in": "path",
"name": "childId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"in": "path",
"name": "guardianId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GuardianRosterDto"
}
}
},
"description": "The updated guardian roster."
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The seat is not a successor, not found, or the guardianship has transitioned."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No guardianship for this minor."
}
},
"summary": "Activates a standby successor guardian so it begins to hold authority.",
"tags": [
"Guardianships"
]
}
},
"/api/v1/identity/guardianships/{childId}/transition": {
"post": {
"parameters": [
{
"in": "path",
"name": "childId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/TransitionGuardianshipRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/TransitionGuardianshipRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/TransitionGuardianshipRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TransitionAuditResultDto"
}
}
},
"description": "The transition was recorded."
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid decisions, or the guardianship has already transitioned."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No active guardianship for this minor that the caller may end — only the\r\n minor themself or the primary guardian may (the same answer for \"not yours\" and \"does not\r\n exist\", #22778)."
}
},
"summary": "Commits the majority authority-transfer for a supervised minor: revokes guardian\r\nauthority and anchors the transition audit.",
"tags": [
"Guardianships"
]
}
},
"/api/v1/identity/history/name-change": {
"get": {
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/VerifiedNameChangeView"
},
"type": "array"
}
}
},
"description": "OK"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
}
},
"summary": "List the account's committed verified-name-change history records (most recent first).",
"tags": [
"NameChangeHistory"
]
}
},
"/api/v1/identity/history/name-change/{auditRecordId}": {
"get": {
"parameters": [
{
"in": "path",
"name": "auditRecordId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/VerifiedNameChangeView"
}
}
},
"description": "OK"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
}
},
"summary": "Read a single committed identity-history record by its audit record id.",
"tags": [
"NameChangeHistory"
]
}
},
"/api/v1/identity/history/name-change/{auditRecordId}/export": {
"get": {
"parameters": [
{
"in": "path",
"name": "auditRecordId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NameChangeHistoryExport"
}
}
},
"description": "OK"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
}
},
"summary": "Export a single committed identity-history record (portable, ZK-safe).",
"tags": [
"NameChangeHistory"
]
}
},
"/api/v1/identity/minor-transition/identity-change": {
"get": {
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IdentityChangeRecordDto"
}
}
},
"description": "OK"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
}
},
"summary": "Read the minor→adult identity-change record. Seam: `getIdentityChange`.",
"tags": [
"MinorTransition"
]
}
},
"/api/v1/identity/minor-transition/revocation-proof": {
"get": {
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RevocationProofDto"
}
}
},
"description": "OK"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
}
},
"summary": "Read the exportable guardian-revocation proof. Seam: `getRevocationProof`.",
"tags": [
"MinorTransition"
]
}
},
"/api/v1/identity/minor-transition/safe-recovery": {
"post": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/InitiateSafeRecoveryRequestBody"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/InitiateSafeRecoveryRequestBody"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/InitiateSafeRecoveryRequestBody"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InitiateSafeRecoveryResult"
}
}
},
"description": "OK"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Conflict"
}
},
"summary": "Initiate guided step-up / assisted recovery after a failed majority verification. Seam:\r\n`initiateSafeRecovery`. The vault stays locked to the adult; control never reverts\r\nto the former guardian.",
"tags": [
"MinorTransition"
]
}
},
"/api/v1/identity/primary-contact-changes": {
"get": {
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/PrimaryContactChangeView"
},
"type": "array"
}
}
},
"description": "OK"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
}
},
"summary": "The caller's primary-contact changes still in progress (`Requested` /\r\n`NewAddressVerified`), most recent first.",
"tags": [
"OpenIdentityChanges"
]
},
"post": {
"description": "Requires a fresh (≤ 5 minutes) GPG 44 medium step-up elevation, `act=contact-change`, on\r\n`X-Step-Up-Token` (Essence.Identity.Auth.Api.Security.IContactChangeStepUpGate; DVS-4.4, TF 1.0 §7.3.1.c).",
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/RequestPrimaryContactChangeRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/RequestPrimaryContactChangeRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/RequestPrimaryContactChangeRequest"
}
}
}
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RequestPrimaryContactChangeResult"
}
}
},
"description": "Created"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Conflict"
}
},
"summary": "Request a primary-contact change; issues a challenge to the new address.",
"tags": [
"PrimaryContactChanges"
]
}
},
"/api/v1/identity/primary-contact-changes/{changeId}": {
"get": {
"parameters": [
{
"in": "path",
"name": "changeId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PrimaryContactChangeView"
}
}
},
"description": "OK"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
}
},
"summary": "Read the change session (masked; ZK-safe).",
"tags": [
"PrimaryContactChanges"
]
}
},
"/api/v1/identity/primary-contact-changes/{changeId}/cancel": {
"post": {
"parameters": [
{
"in": "path",
"name": "changeId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CancelPrimaryContactChangeResult"
}
}
},
"description": "OK"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Conflict"
}
},
"summary": "Cancel the change during the trust window (retain the old contact).",
"tags": [
"PrimaryContactChanges"
]
}
},
"/api/v1/identity/primary-contact-changes/{changeId}/cascade": {
"get": {
"parameters": [
{
"in": "path",
"name": "changeId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PrimaryContactCascadeView"
}
}
},
"description": "OK"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
}
},
"summary": "Read the per-consumer cross-service cascade projection.",
"tags": [
"PrimaryContactChanges"
]
}
},
"/api/v1/identity/primary-contact-changes/{changeId}/commit": {
"post": {
"description": "The cutover is the moment the contact details change, so it requires its own fresh (≤ 5 minutes)\r\n`act=contact-change` step-up elevation (DVS-4.4, TF 1.0 §7.3.1.c) — the one taken to open the\r\nchange is at least a trust window old by now.",
"parameters": [
{
"in": "path",
"name": "changeId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CommitPrimaryContactChangeResult"
}
}
},
"description": "OK"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Conflict"
}
},
"summary": "Commit cutover once the trust window has elapsed; emits the cascade event.",
"tags": [
"PrimaryContactChanges"
]
}
},
"/api/v1/identity/primary-contact-changes/{changeId}/resend": {
"post": {
"parameters": [
{
"in": "path",
"name": "changeId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/ResendPrimaryContactChallengeRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/ResendPrimaryContactChallengeRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ResendPrimaryContactChallengeRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ResendPrimaryContactChallengeResult"
}
}
},
"description": "OK"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Conflict"
}
},
"summary": "Re-issue the challenge to the NEW address.",
"tags": [
"PrimaryContactChanges"
]
}
},
"/api/v1/identity/primary-contact-changes/{changeId}/revalidate-factors": {
"post": {
"parameters": [
{
"in": "path",
"name": "changeId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/RevalidatePrimaryContactFactorsRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/RevalidatePrimaryContactFactorsRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/RevalidatePrimaryContactFactorsRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RevalidatePrimaryContactFactorsResult"
}
}
},
"description": "OK"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Conflict"
}
},
"summary": "Re-validate recovery factors / active shares during the trust window.",
"tags": [
"PrimaryContactChanges"
]
}
},
"/api/v1/identity/primary-contact-changes/{changeId}/verify-new-address": {
"post": {
"parameters": [
{
"in": "path",
"name": "changeId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/VerifyNewPrimaryContactAddressRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/VerifyNewPrimaryContactAddressRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/VerifyNewPrimaryContactAddressRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/VerifyNewPrimaryContactAddressResult"
}
}
},
"description": "OK"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Conflict"
}
},
"summary": "Prove control of the NEW address by submitting the one-time code.",
"tags": [
"PrimaryContactChanges"
]
}
},
"/api/v1/identity/returning-national/queue": {
"get": {
"parameters": [
{
"in": "query",
"name": "limit",
"schema": {
"default": 100,
"format": "int32",
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/ReturningNationalReceiptResult"
},
"type": "array"
}
}
},
"description": "The held queue."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The caller is not an administrator."
}
},
"summary": "Returns the business-admin bootstrap-acceptance queue — held cases awaiting\r\napprove / hold / decline, oldest first. Admin-only.",
"tags": [
"ReturningNational"
]
}
},
"/api/v1/identity/returning-national/queue/{decisionId}/resolve": {
"post": {
"parameters": [
{
"in": "path",
"name": "decisionId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/ResolveReturningNationalBootstrapRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/ResolveReturningNationalBootstrapRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ResolveReturningNationalBootstrapRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ReturningNationalReceiptResult"
}
}
},
"description": "The resolved decision + receipt."
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid action."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The caller is not an administrator."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No such decision."
}
},
"summary": "Business-admin resolves a held bootstrap case (approve / hold / decline).\r\nApproval credits the domestic assurance and meters the implied identity\r\ncheck. Admin-only.",
"tags": [
"ReturningNational"
]
}
},
"/api/v1/identity/returning-national/{intakeId}/bootstrap": {
"post": {
"parameters": [
{
"in": "path",
"name": "intakeId",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/BootstrapReturningNationalRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/BootstrapReturningNationalRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/BootstrapReturningNationalRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ReturningNationalReceiptResult"
}
}
},
"description": "The bootstrap decision (accepted or held) + receipt."
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid request."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The caller is not authenticated."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No intake with that id was opened by the caller."
},
"503": {
"description": "The intake could not be read; nothing was credited."
}
},
"summary": "Runs the returning-national bootstrap acceptance gate for the authenticated\r\ncaller's intake. The origin jurisdiction, scheme and foreign LoA are those the\r\ncaller's intake recorded (read from the Instance service) — the body cannot\r\nsupply them (#14018). Returns the audited decision + user receipt. On an\r\nautomatic accept the subject's authoritative identity assurance is credited\r\nto the mapped domestic level; otherwise the case is held for the\r\nbusiness-admin queue.",
"tags": [
"ReturningNational"
]
}
},
"/api/v1/identity/smart/launch-contexts": {
"post": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/IssueSmartLaunchContextRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/IssueSmartLaunchContextRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/IssueSmartLaunchContextRequest"
}
}
}
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IssueSmartLaunchContextResult"
}
}
},
"description": "Created"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden"
}
},
"summary": "Mint a one-time launch context. Called by a trusted EHR at the moment it\r\nlaunches a SMART app; the returned launch token is handed to the app and\r\nis redeemable exactly once.",
"tags": [
"SmartLaunch"
]
}
},
"/api/v1/identity/smart/token-exchange": {
"post": {
"description": "Contracted refusals carry a `code`: `unregistered-iss` (400),\r\n`launch-token-invalid` (401), `scope-not-permitted` (403). A\r\nconsumer distinguishes these from an outage by that code — a refusal is a\r\ndecision, anything else is an unknown.",
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/SmartTokenExchangeRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/SmartTokenExchangeRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/SmartTokenExchangeRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SmartTokenExchangeResponse"
}
}
},
"description": "OK"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden"
}
},
"summary": "Exchange an EHR's one-time SMART launch token for a scoped clinician\r\nsession. The exchange is performed AS the clinician (the caller's bearer\r\ntoken), never as a service principal, so the resulting launch is\r\nattributable to a person.",
"tags": [
"SmartLaunch"
]
}
},
"/api/v1/identity/smart/trusted-issuers": {
"get": {
"parameters": [
{
"in": "query",
"name": "organizationId",
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/TrustedEhrIssuerDto"
},
"type": "array"
}
}
},
"description": "OK"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden"
}
},
"summary": "List the trusted-EHR issuer registry.",
"tags": [
"SmartLaunch"
]
},
"post": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/RegisterTrustedEhrIssuerRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/RegisterTrustedEhrIssuerRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/RegisterTrustedEhrIssuerRequest"
}
}
}
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RegisterTrustedEhrIssuerResponse"
}
}
},
"description": "Created"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden"
}
},
"summary": "Register an EHR issuer as trusted. Idempotent: re-registering an existing\r\nissuer returns its id rather than failing, so provisioning can be re-run.",
"tags": [
"SmartLaunch"
]
}
},
"/api/v1/identity/smart/trusted-issuers/{issuerId}/status": {
"post": {
"parameters": [
{
"in": "path",
"name": "issuerId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/SetTrustedEhrIssuerStatusRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/SetTrustedEhrIssuerStatusRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/SetTrustedEhrIssuerStatusRequest"
}
}
}
},
"responses": {
"204": {
"description": "No Content"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
}
},
"summary": "Suspend, withdraw, or reinstate a trusted issuer. Withdrawal is terminal;\r\na suspension is reinstatable.",
"tags": [
"SmartLaunch"
]
}
},
"/api/v1/identity/verified-name-changes": {
"get": {
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/VerifiedNameChangeView"
},
"type": "array"
}
}
},
"description": "OK"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
}
},
"summary": "The caller's verified-name changes still in progress (`Requested` / `Reattested`),\r\nmost recent first.",
"tags": [
"OpenIdentityChanges"
]
},
"post": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/RequestVerifiedNameChangeRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/RequestVerifiedNameChangeRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/RequestVerifiedNameChangeRequest"
}
}
}
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RequestVerifiedNameChangeResult"
}
}
},
"description": "Created"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Conflict"
}
},
"summary": "Open a verified-name-change session (records the old/new name hashes).",
"tags": [
"VerifiedNameChanges"
]
}
},
"/api/v1/identity/verified-name-changes/{changeId}": {
"get": {
"parameters": [
{
"in": "path",
"name": "changeId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/VerifiedNameChangeView"
}
}
},
"description": "OK"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
}
},
"summary": "Read the change session (masked; ZK-safe).",
"tags": [
"VerifiedNameChanges"
]
}
},
"/api/v1/identity/verified-name-changes/{changeId}/cancel": {
"post": {
"parameters": [
{
"in": "path",
"name": "changeId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CancelVerifiedNameChangeResult"
}
}
},
"description": "OK"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Conflict"
}
},
"summary": "Cancel the change before commit (retain the prior verified name).",
"tags": [
"VerifiedNameChanges"
]
}
},
"/api/v1/identity/verified-name-changes/{changeId}/commit": {
"post": {
"parameters": [
{
"in": "path",
"name": "changeId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/CommitVerifiedNameChangeRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/CommitVerifiedNameChangeRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/CommitVerifiedNameChangeRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CommitVerifiedNameChangeResult"
}
}
},
"description": "OK"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Conflict"
}
},
"summary": "Commit cutover; broadcasts the ZK-safe verified-name-change event.",
"tags": [
"VerifiedNameChanges"
]
}
},
"/api/v1/identity/verified-name-changes/{changeId}/reattest": {
"post": {
"parameters": [
{
"in": "path",
"name": "changeId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/ReattestVerifiedNameChangeRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/ReattestVerifiedNameChangeRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ReattestVerifiedNameChangeRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ReattestVerifiedNameChangeResult"
}
}
},
"description": "OK"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Conflict"
}
},
"summary": "Record that the new name was re-attested against fresh identity evidence.",
"tags": [
"VerifiedNameChanges"
]
}
},
"/api/v1/internal/directory/minors/{minorUserId}/guardians/{guardianUserId}/corroboration": {
"get": {
"parameters": [
{
"description": "The supervised minor.",
"in": "path",
"name": "minorUserId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"description": "The person claiming to be the minor's guardian.",
"in": "path",
"name": "guardianUserId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GuardianshipCorroborationResult"
}
}
},
"description": "The corroboration. `corroborated=false` means \"this person does not currently hold\r\nguardian authority over this minor\" — it does not say whether the minor has a guardianship\r\nat all, and the caller must treat it as \"do not supervise\", never as \"retry\"."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No valid bearer token."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The bearer is not a service principal."
}
},
"summary": "Whether a person holds active guardian authority over a minor right now.",
"tags": [
"InternalGuardianshipCorroboration"
]
}
},
"/api/v1/internal/directory/organisations/{organizationId}/notification-audience": {
"get": {
"parameters": [
{
"description": "The organisation whose audience is resolved.",
"in": "path",
"name": "organizationId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OrganisationNotificationAudienceDto"
}
}
},
"description": "The lookup completed. An empty `recipientIds` means the organisation has no active\r\nadministrator on record — the caller must record that, never treat it as delivered."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No valid bearer token."
}
},
"summary": "Resolves who an organisation-addressed notification is for: the organisation's active\r\nadministrators, as user ids (#11198). EPIC 66 fans the notice out to them and resolves each\r\none's contact through M:Essence.Identity.Auth.Api.Controllers.RecipientDirectoryController.GetRecipientContact(System.Guid,System.Threading.CancellationToken,System.Boolean) at send time.",
"tags": [
"RecipientDirectory"
]
}
},
"/api/v1/internal/directory/orgs/{orgId}/executor-officers/{officerUserId}/attestation": {
"get": {
"parameters": [
{
"description": "The organisation whose roster to consult.",
"in": "path",
"name": "orgId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"description": "The officer to resolve.",
"in": "path",
"name": "officerUserId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExecutorOfficerAttestationResult"
}
}
},
"description": "The attestation. `attested=false` means \"this organisation does not currently attest\r\nthis officer\" — it does not distinguish an unknown officer from an unverified one, and the\r\ncaller must treat it as \"cannot claim verified\", never as \"verified elsewhere\"."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No valid bearer token."
}
},
"summary": "Whether an officer is rostered and identity-verified by an organisation right now.",
"tags": [
"InternalExecutorRoster"
]
}
},
"/api/v1/internal/directory/orgs/{orgId}/members/{userId}/standing": {
"get": {
"parameters": [
{
"description": "The organisation.",
"in": "path",
"name": "orgId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"description": "The user.",
"in": "path",
"name": "userId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OrgMembershipStandingDto"
}
}
},
"description": "The standing. `activeMember=false` means not a current member with an active account; it\r\ndoes not say why."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No valid bearer token."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "A token that is not a service principal."
}
},
"summary": "Whether a user is an active member of an organisation, and whether they administer it.",
"tags": [
"InternalOrgMembershipStanding"
]
}
},
"/api/v1/internal/directory/orgs/{organizationId}/sso-coverage": {
"get": {
"description": "\n\r\n The EPIC 9 IdP calls this for the `affectedMemberCount` on the SSO-enforcement\r\n review step (FR-09.041, issue #7264) — the number an org admin is shown immediately\r\n before an irreversible, org-wide sign-in change. Auth answers it because enforcement is\r\n applied through the domain-keyed org-IdP directory and Auth is the service that holds\r\n the accounts on those domains.\r\n \r\n\n\r\n Carries no PII whatsoever — an aggregate count and the organisation's own proven-domain\r\n tally — and so is the least sensitive member of this controller, but it keeps the same\r\n in-mesh-only trust boundary and the platform default rate-limit policy (SEC-004) as its\r\n siblings rather than opting out of either.\r\n ",
"parameters": [
{
"description": "The organisation whose coverage is being sized.",
"in": "path",
"name": "organizationId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"description": "Optional, repeatable: the `allowed-domains` scope's domain set. Narrows the\r\norganisation's proven domains; never extends them. Omit for the whole organisation.",
"in": "query",
"name": "domain",
"schema": {
"items": {
"type": "string"
},
"type": "array"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OrgSsoCoverageDto"
}
}
},
"description": "The sizing completed. `resolved=false` means the organisation holds no current\r\ndomain proof in scope, so the population is unknown — the caller must not render\r\nit as zero."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No valid bearer token."
}
},
"summary": "Sizes the population an organisation's domain-keyed sign-in change would reach.",
"tags": [
"IdentityDirectory"
]
}
},
"/api/v1/internal/directory/professional-advisers/{adviserUserId}/authorisation": {
"get": {
"description": "\n\r\n The register answers, not the token. A role claim is a cached projection that a\r\n still-valid access token carries past a revocation, so an adviser struck off this morning\r\n would keep presenting `professional-adviser` until their token expired. The check reads\r\n the register at the moment the act is attempted.\r\n \r\n\n\r\n Four verdicts, not a boolean. A relying service has two decisions to make, and a\r\n boolean cannot carry both. `not-registered` — nobody holds a professional mandate over\r\n this person — is genuinely different from `not-authorised`, and collapsing them would\r\n force the caller to refuse an independent adviser whom a client named individually, breaking\r\n a case the journey already supports. `no-live-assignment` is separated again because it\r\n is the one failure a supervisor can fix, by assigning the case.\r\n \r\n\n\r\n Capabilities are a ceiling. The agency permission set on the response must be\r\n intersected with what the client's own delegation conveyed. The agency may narrow\r\n consent; it may never widen it.\r\n \r\n\n\r\n Same trust boundary as the sibling routes: service JWT, in-mesh only over Istio STRICT mTLS,\r\n never gateway-exposed, platform default rate-limit retained. It is more informative than the\r\n safeguarding seam beside it — it names the agency behind a verdict, which the relying\r\n service records for attribution — and that is precisely why it stays inside the mesh.\r\n ",
"parameters": [
{
"description": "The adviser to check.",
"in": "path",
"name": "adviserUserId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"description": "The client they propose to act for. Omit to ask only the general professional-standing\r\nquestion, which then never returns `no-live-assignment`.",
"in": "query",
"name": "clientUserId",
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProfessionalAdviserAuthorisationResult"
}
}
},
"description": "The authority verdict."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No valid bearer token."
}
},
"summary": "Whether a user is an authorised professional adviser right now, and — when a client\r\nis named — whether a recognised agency has actually put them on that client's case (journey\r\n`debt-relief-order-money-adviser-to-creditor-moratorium`, debt-2026-08-20-030).",
"tags": [
"IdentityDirectory"
]
}
},
"/api/v1/internal/directory/recipients/{userId}/contact": {
"get": {
"parameters": [
{
"description": "The user-principal id to resolve.",
"in": "path",
"name": "userId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"description": "DVS-7.2b: `true` only for a notice the holder-account procedure owes a closed account (the\r\nclosure notice with its cancel link, its cancellation, the closure lifecycle notices, the security\r\nalerts). Absent or false, a deactivated account is not deliverable (FR-66.127), as before DVS-7.2b.",
"in": "query",
"name": "owedToClosedAccount",
"schema": {
"default": false,
"type": "boolean"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RecipientContactDto"
}
}
},
"description": "The lookup completed. `exists=false` means no active account resolves to the id (or a\r\ndeactivated one, unless `owedToClosedAccount=true`); `email`/`phone` are null when\r\nthe directory holds no verified value."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No valid bearer token."
}
},
"summary": "Resolves the deliverable contact (email / phone) for a user principal.",
"tags": [
"RecipientDirectory"
]
}
},
"/api/v1/internal/directory/safeguarding-officers/{officerUserId}/authorisation": {
"get": {
"description": "\n\r\n The register answers, not the token. A role claim is a cached projection that a\r\n still-valid access token carries past a revocation. A countersignature recorded against a\r\n stale claim would name an officer whose designation had already ended, in the one artefact\r\n whose value is that it is true — so the check reads the register at the moment the\r\n signature is recorded.\r\n \r\n\n\r\n Non-enumerable and non-PII. The response is a boolean and an instant. \"Never\r\n designated\", \"designated but unverified\", \"stood down\" and \"their authority's recognition\r\n lapsed\" are deliberately indistinguishable, and a 200 is returned for an unknown id, so the\r\n endpoint cannot be used to discover who is on a register or why someone is not.\r\n ",
"parameters": [
{
"description": "The user-principal id to check.",
"in": "path",
"name": "officerUserId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SafeguardingOfficerAuthorisationResult"
}
}
},
"description": "The authorisation answer."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No valid bearer token."
}
},
"summary": "Whether a user is an authorised safeguarding officer right now — the seam EPIC 57's\r\nsafeguarding case service resolves before it accepts a decision-maker or a co-authoriser\r\n(journey `attorney-abuse-safeguarding-report-to-opg-investigation`,\r\ndebt-2026-08-18-084).",
"tags": [
"IdentityDirectory"
]
}
},
"/api/v1/internal/directory/users/{userId}/assurance-posture": {
"get": {
"description": "\n\r\n Exists so a relying service can establish that a party is identity-attested\r\n without that party asserting it and without the service receiving any\r\n identity attribute (debt-2026-08-22-005, journey\r\n `reciprocal-field-disclosure-negotiation-between-contacts`). EPIC 6's\r\n reciprocal atomic-commit gate is the first caller: before two people's fields\r\n are disclosed to each other it asks the identity authority, rather than\r\n trusting a self-reported badge.\r\n \r\n\n\r\n Non-PII by contract. The response is a boolean, a level name, an\r\n attesting-source label and an instant. It deliberately does NOT carry the\r\n proofing policy, provenance, audit anchor or recovery disposition that the\r\n account holder's own `assurance` surface returns — a relying party learns\r\n that the person was attested, never how.\r\n \r\n\n\r\n Same trust boundary as the sibling routes on this controller: service JWT,\r\n in-mesh only over Istio STRICT mTLS, never gateway-exposed, platform default\r\n rate-limit retained because this is an enumeration surface by nature.\r\n ",
"parameters": [
{
"description": "The party to resolve.",
"in": "path",
"name": "userId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AssurancePostureResult"
}
}
},
"description": "A posture was resolved. `verified=false` is a real answer — the party is\r\nknown but is not currently identity-attested (never proofed, or the attestation\r\nhas gone stale) — and callers must treat it as \"not attested\", never as an error."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No valid bearer token."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No assurance record exists for the id at all."
}
},
"summary": "Resolves a party's identity assurance posture — attested or not, at what\r\nlevel, by whom, and when.",
"tags": [
"IdentityDirectory"
]
}
},
"/api/v1/internal/directory/users/{userId}/billing-profile": {
"get": {
"parameters": [
{
"description": "The user the invoice is addressed to.",
"in": "path",
"name": "userId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BillingProfileDto"
}
}
},
"description": "The lookup completed. `exists=false` means no account that has not been erased resolves to the id."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No valid bearer token."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The caller is not Billing's bill-to service principal."
}
},
"summary": "Resolves the bill-to name and email of a user.",
"tags": [
"BillingProfileDirectory"
]
}
},
"/api/v1/internal/directory/users/{userId}/identity-attributes": {
"get": {
"parameters": [
{
"description": "The user-principal id to resolve.",
"in": "path",
"name": "userId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UserIdentityAttributesDto"
}
}
},
"description": "The lookup completed. `exists=false` means no active account resolves to the id — the\r\ncaller must treat that as \"unknown\", never as \"nothing matched\"."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No valid bearer token."
}
},
"summary": "Resolves the matchable identity attributes (email / phone / name) for a user principal.",
"tags": [
"IdentityDirectory"
]
}
},
"/api/v1/internal/directory/users/{userId}/nameability": {
"get": {
"description": "\n\r\n Exists so a service that will later need to name this person can discover, at the moment the\r\n user is configuring the thing, that it will not be able to (debt-2026-08-27-145). EPIC 15's\r\n dead-man's-switch is the first caller: its welfare check tells a nominated contact who to\r\n check on, and fails closed when the holder recorded no name. Asking here moves that failure\r\n from the escalation — where nobody is contacted and the holder never learns — to the\r\n configuration screen, in front of the one person who can fix it.\r\n \r\n\n\r\n Non-PII by contract. Two booleans and the echoed id; the name itself is never\r\n returned. `GET recipients/{userId}/contact` remains the only route that discloses it,\r\n and only to the send path that must render it. That is what makes this one safe to call on\r\n an ordinary configuration write.\r\n \r\n\n\r\n Same trust boundary as the sibling routes: service JWT, in-mesh only over Istio STRICT mTLS,\r\n never gateway-exposed. A 200 is returned for an unknown id (`exists=false`) so the\r\n route cannot be used to enumerate which ids are real.\r\n ",
"parameters": [
{
"description": "The user-principal id to check.",
"in": "path",
"name": "userId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SubjectNameabilityDto"
}
}
},
"description": "The nameability answer. `exists=false` means \"unknown\", never \"this person has no\r\nname\" — callers must not treat the two the same."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No valid bearer token."
}
},
"summary": "Whether a principal can be named to a third party — i.e. whether a notice addressed\r\nto someone else could say who it is about.",
"tags": [
"IdentityDirectory"
]
}
},
"/api/v1/internal/shared-devices/attestations/verify": {
"post": {
"description": "Always 200 with a verdict, because every verdict is information the caller records:\r\n`attested`, `malformed`, `unenrolled`, `signature-invalid`,\r\n`revoked`, `binding-mismatch` or `stale`. Only `attested` may be\r\nrecorded as \"made on this device\". A capture that carried no attestation at all never\r\nreaches this endpoint — \"no shared device involved\" is the caller's own fact.",
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/VerifySharedDeviceAttestationRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/VerifySharedDeviceAttestationRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/VerifySharedDeviceAttestationRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SharedDeviceAttestationVerdictDto"
}
}
},
"description": "The verdict."
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "A required field is missing."
}
},
"summary": "Decides one attestation.",
"tags": [
"SharedDeviceAttestations"
]
}
},
"/api/v1/mfa/backup-codes/regenerate": {
"post": {
"description": "Requires a fresh (≤ 5 minutes) `act=authenticator-enrolment` elevation (DVS-4.4b). A\r\nbackup code completes a sign-in's second step and satisfies the step-ups that accept one, so\r\nissuing a new set adds an authenticator.",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RegenerateMfaBackupCodesResult"
}
}
},
"description": "OK"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
}
},
"summary": "Regenerate backup codes for the authenticated user",
"tags": [
"Mfa"
]
}
},
"/api/v1/mfa/disable": {
"post": {
"description": "Requires a fresh (≤ 5 minutes) `act=second-factor-removal` elevation on\r\n`X-Step-Up-Token` (Essence.Identity.Auth.Api.Security.ISecondFactorRemovalStepUpGate; DVS-4.4d, TF 1.0 §7.3.1.c),\r\nproved with a passkey, an authenticator-app code or a text-message code (the factor being\r\nremoved counts), never the password, an emailed code or a backup code. The password in the body\r\nis still checked as well. Without the elevation, a session and the password removed the factor\r\nand left the account at the password floor for every other medium gate. Checked before the\r\npassword, so a refusal says nothing about whether the password was right.",
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/DisableMfaCommand"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/DisableMfaCommand"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/DisableMfaCommand"
}
}
},
"description": "Disable MFA request"
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DisableMfaResult"
}
}
},
"description": "OK"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No acceptable step-up elevation (`step-up-required`)."
}
},
"summary": "Disable MFA for the authenticated user (requires a fresh step-up and the current password)",
"tags": [
"Mfa"
]
}
},
"/api/v1/mfa/enable/totp": {
"post": {
"description": "Requires a fresh (≤ 5 minutes) `act=authenticator-enrolment` elevation on\r\n`X-Step-Up-Token`, proved with a factor the account already has (DVS-4.4b): the secret\r\nreturned here IS the authenticator, so whoever receives it holds the factor. Confirming the\r\nstaged enrolment (`POST /mfa/verify`) is not gated again: it needs a code from this\r\nsecret, which only the elevated caller of this endpoint received.",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EnableMfaWithTotpResult"
}
}
},
"description": "OK"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Conflict"
}
},
"summary": "Enable TOTP (Google Authenticator) MFA for the authenticated user",
"tags": [
"Mfa"
]
}
},
"/api/v1/mfa/enrolment-options": {
"get": {
"description": "Held items open only from a medium session (DVS-4.3), so the set-up surfaces offer at least two medium\r\nroutes — a passkey and an authenticator app — so that losing one does not drop the holder below it. A\r\ntext-message code is offered once its enrolment is on (DVS-4.3b, `POST /api/v1/mfa/sms/enrolment`, after\r\nthe number is verified) and listed as `not-available-yet` while it is staged off.",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MediumEnrolmentOptionsDto"
}
}
},
"description": "OK"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
}
},
"summary": "The medium routes the server offers to set up, which are offered, and which the account has.",
"tags": [
"MediumEnrolmentOptions"
]
}
},
"/api/v1/mfa/send/email": {
"post": {
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SendEmailOtpResult"
}
}
},
"description": "OK"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"429": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Too Many Requests"
}
},
"summary": "Send an OTP code via email to the authenticated user's verified email address",
"tags": [
"Mfa"
]
}
},
"/api/v1/mfa/send/sms": {
"post": {
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SendSmsOtpResult"
}
}
},
"description": "OK"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"429": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Too Many Requests"
}
},
"summary": "Send an OTP code via SMS to the authenticated user's verified phone number",
"tags": [
"Mfa"
]
}
},
"/api/v1/mfa/sms/enrolment": {
"post": {
"description": "Requires a fresh (≤ 5 minutes) `act=authenticator-enrolment` elevation on `X-Step-Up-Token`\r\n(DVS-4.4b). Answers the backup codes once.",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SmsEnrolmentResponse"
}
}
},
"description": "Enrolled; the masked number and the backup codes (shown once)."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "A step-up is required (`step-up-required`)."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The subscription does not include text-message codes."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not enrolled: no number, an unverified number, a second factor already on, or text-message enrolment not available yet."
}
},
"summary": "Use the verified number on the account for sign-in and step-up codes.",
"tags": [
"SmsEnrolment"
]
}
},
"/api/v1/mfa/status": {
"get": {
"description": "Issue #4714. This surface carried three mutations and no read, so a client could CHANGE\r\nthe MFA state and never OBSERVE it. Settings → Security consequently hardcoded its\r\ntwo-factor toggle to on — telling every user their authenticator app was enabled, true or\r\nnot — and let them switch it off with no effect.\r\n \r\nThere is no `enrolledAt`: the domain records no enrolment timestamp, and serving a\r\nplausible date for \"when did you turn this on\" is the class of invention this endpoint\r\nexists to remove. See Essence.Identity.Auth.Application.Queries.Mfa.MfaStatusDto.",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MfaStatusDto"
}
}
},
"description": "OK"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
}
},
"summary": "Report whether the authenticated account has a second factor, and what remains of its\r\nbackup codes.",
"tags": [
"Mfa"
]
}
},
"/api/v1/mfa/verify": {
"post": {
"description": "Answers with a verdict, so a rejected code is a 200 whose `isValid` AND `success`\r\nare both `false` (#7240) — never a 200 that only one field contradicts. A caller must\r\nread a flag; the status code alone distinguishes only \"we could not check\" from \"we did\".\r\nSee Essence.Identity.Auth.Application.Commands.Mfa.VerifyMfaResult for why the refusal is not a 401.",
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/VerifyMfaCommand"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/VerifyMfaCommand"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/VerifyMfaCommand"
}
}
},
"description": "MFA verification request"
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/VerifyMfaResult"
}
}
},
"description": "OK"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
}
},
"summary": "Verify an MFA code",
"tags": [
"Mfa"
]
}
},
"/api/v1/orgs/executor-officers": {
"get": {
"parameters": [
{
"description": "Include removed officers (the audit view). Defaults to false.",
"in": "query",
"name": "includeRemoved",
"schema": {
"default": false,
"type": "boolean"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExecutorRosterResult"
}
}
},
"description": "The roster plus its header counts."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The caller carries no organisation claim."
}
},
"summary": "Returns the caller's organisation's executor roster.",
"tags": [
"OrgExecutorOfficers"
]
},
"post": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/AddExecutorOfficerRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/AddExecutorOfficerRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/AddExecutorOfficerRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExecutorOfficerRow"
}
}
},
"description": "The officer's roster row."
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The request failed validation."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The caller carries no organisation claim."
}
},
"summary": "Adds an individual to the roster, unverified. Idempotent: re-adding someone already on the\r\nroster returns their existing row, and re-adding a removed officer reinstates them —\r\nunverified, because the reason they left may be the reason their evidence no longer holds.",
"tags": [
"OrgExecutorOfficers"
]
}
},
"/api/v1/orgs/executor-officers/{officerUserId}/removal": {
"post": {
"parameters": [
{
"in": "path",
"name": "officerUserId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/RemoveExecutorOfficerRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/RemoveExecutorOfficerRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/RemoveExecutorOfficerRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExecutorOfficerRow"
}
}
},
"description": "The officer's removed roster row."
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The request failed validation."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The caller carries no organisation claim."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No such officer is on this organisation's roster."
}
},
"summary": "Removes an officer from the roster and cascades that removal to every estate grant they hold.",
"tags": [
"OrgExecutorOfficers"
]
}
},
"/api/v1/orgs/executor-officers/{officerUserId}/verification": {
"post": {
"parameters": [
{
"in": "path",
"name": "officerUserId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/VerifyExecutorOfficerRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/VerifyExecutorOfficerRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/VerifyExecutorOfficerRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExecutorOfficerRow"
}
}
},
"description": "The officer's updated roster row."
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The request failed validation."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The caller carries no organisation claim."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No such officer is on this organisation's roster."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The officer has been removed and cannot be verified."
}
},
"summary": "Records that the officer's identity has been verified — the transition that makes the roster\r\nattest them to a consuming service.",
"tags": [
"OrgExecutorOfficers"
]
}
},
"/api/v1/orgs/{orgId}/expiring-verifications": {
"get": {
"parameters": [
{
"in": "path",
"name": "orgId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"in": "query",
"name": "sortBy",
"schema": {
"default": "daysToExpiry",
"type": "string"
}
},
{
"in": "query",
"name": "window",
"schema": {
"default": 30,
"format": "int32",
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExpiringVerificationsCohortResult"
}
}
},
"description": "The cohort + aggregate counts."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The caller is not an administrator of this org."
}
},
"summary": "Returns the org's expiring-verifications cohort within the look-ahead\r\nwindow (days), sorted by days-to-expiry ascending, with\r\nthe aggregate counts the worklist header shows.",
"tags": [
"OrgExpiringVerifications"
]
}
},
"/api/v1/orgs/{orgId}/expiring-verifications/record": {
"post": {
"parameters": [
{
"in": "path",
"name": "orgId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/RecordVerificationRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/RecordVerificationRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/RecordVerificationRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExpiringVerificationRow"
}
}
},
"description": "The recorded/updated cohort row."
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The caller is not an administrator of this org."
}
},
"summary": "Records (upserts) an org member verification into the cohort — the\r\ningestion side of the base capability, called by the org proofing /\r\nverification seam so the worklist has data to act on.",
"tags": [
"OrgExpiringVerifications"
]
}
},
"/api/v1/orgs/{orgId}/expiring-verifications/request-recheck": {
"post": {
"parameters": [
{
"in": "path",
"name": "orgId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/VerificationIdsRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/VerificationIdsRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/VerificationIdsRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/VerificationActionResult"
}
}
},
"description": "The action outcome."
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The caller is not an administrator of this org."
}
},
"summary": "Requests a recheck for one or more verifications (per-row or bulk).",
"tags": [
"OrgExpiringVerifications"
]
}
},
"/api/v1/orgs/{orgId}/expiring-verifications/send-reminder": {
"post": {
"parameters": [
{
"in": "path",
"name": "orgId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/VerificationIdsRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/VerificationIdsRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/VerificationIdsRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/VerificationActionResult"
}
}
},
"description": "The action outcome."
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The caller is not an administrator of this org."
}
},
"summary": "Sends a renewal reminder for one or more verifications (per-row or bulk).",
"tags": [
"OrgExpiringVerifications"
]
}
},
"/api/v1/orgs/{orgId}/grant-approvals": {
"get": {
"parameters": [
{
"in": "path",
"name": "orgId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"description": "The pending grants, enveloped as `{ data: [...] }`."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The caller is not an administrator of this org."
}
},
"summary": "Lists the grants awaiting the signed-in owner's co-sign. This is the collection\r\nroot: `GET /api/v1/orgs/{orgId}/grant-approvals`.",
"tags": [
"OrgGrantApprovals"
]
}
},
"/api/v1/orgs/{orgId}/grant-approvals/{grantId}/decision": {
"post": {
"parameters": [
{
"in": "path",
"name": "orgId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"in": "path",
"name": "grantId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/GrantApprovalDecisionRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/GrantApprovalDecisionRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/GrantApprovalDecisionRequest"
}
}
}
},
"responses": {
"200": {
"description": "The updated grant, enveloped as `{ data: {...} }`."
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The decision verb is unknown, or a rejection carries no reason."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The caller is not an admin of this org, or is the grant's own issuer."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No such grant within this org."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The grant is already terminal, or this owner has already co-signed it."
}
},
"summary": "Records an approve/reject decision on a pending grant. On the final required\r\napproval the grant transitions to `active` and the delegate is notified\r\nserver-side (outbox-backed integration event).",
"tags": [
"OrgGrantApprovals"
]
}
},
"/api/v1/orgs/{orgId}/member-invitations": {
"post": {
"parameters": [
{
"in": "path",
"name": "orgId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/InviteOrganizationMemberRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/InviteOrganizationMemberRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/InviteOrganizationMemberRequest"
}
}
}
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InviteOrganizationMemberResult"
}
}
},
"description": "The invitation was issued and delivered."
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No invitee address, or it is not a valid address."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The caller does not administer this organisation."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The invitation could not be delivered and has been withdrawn."
}
},
"summary": "Invites a person to join this organisation as a member. The invitee receives an acceptance\r\nlink by email; accepting provisions their account (they set their own password on their own\r\ndevice) and makes them a member, so their access token then carries this organisation's\r\n`org_id`.",
"tags": [
"OrgMemberInvitations"
]
}
},
"/api/v1/orgs/{orgId}/operational-roles": {
"post": {
"parameters": [
{
"in": "path",
"name": "orgId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/SetOperationalRoleRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/SetOperationalRoleRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/SetOperationalRoleRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SetOrgOperationalRoleResult"
}
}
},
"description": "The member's operational roles after the change. Re-granting a held role is a no-op\r\nand still returns 200 — an administrator retrying is not an error."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The caller does not administer this organisation, the role is not one an organisation\r\nmay issue (`role-not-grantable`), or the recipient does not currently belong to\r\nthis organisation (`recipient-not-in-organization`)."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No account exists for the recipient (`recipient-unknown`)."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The recipient's account is deactivated (`recipient-inactive`), or the role is\r\ngranted in the organisation portal's Members screen (`issued-through-org-portal`)."
}
},
"summary": "Grants an operational role to a member of this organisation.",
"tags": [
"OrgOperationalRoles"
]
}
},
"/api/v1/orgs/{orgId}/operational-roles/catalogue": {
"get": {
"description": "Requires org-admin because the catalogue is the menu of authority an administrator is\r\nabout to hand out; it is not a public description of the platform.",
"parameters": [
{
"in": "path",
"name": "orgId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/OperationalRoleCatalogueEntryDto"
},
"type": "array"
}
}
},
"description": "The catalogue."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The caller does not administer this organisation."
}
},
"summary": "The roles this organisation may issue, with what each one lets the holder do.",
"tags": [
"OrgOperationalRoles"
]
}
},
"/api/v1/orgs/{orgId}/operational-roles/holders": {
"get": {
"parameters": [
{
"in": "path",
"name": "orgId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OrgOperationalRoleHoldersResult"
}
}
},
"description": "The holders. `truncated=true` means the roster scan hit its ceiling and the list\r\nmay be incomplete — it must not be read as \"nobody else holds this\"."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The caller does not administer this organisation."
}
},
"summary": "The organisation's members who currently hold an operational role.",
"tags": [
"OrgOperationalRoles"
]
}
},
"/api/v1/orgs/{orgId}/operational-roles/{userId}/{role}": {
"delete": {
"description": "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\r\nmust be able to strip a role from somebody it has just offboarded, which is exactly\r\nwhen the relationship is no longer live.",
"parameters": [
{
"in": "path",
"name": "orgId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"in": "path",
"name": "userId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"in": "path",
"name": "role",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SetOrgOperationalRoleResult"
}
}
},
"description": "The member's operational roles after the change."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The caller does not administer this organisation, or the role/recipient is out of scope."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No account exists for the recipient."
}
},
"summary": "Withdraws an operational role from a member.",
"tags": [
"OrgOperationalRoles"
]
}
},
"/api/v1/orgs/{orgId}/scoped-admin-grants": {
"post": {
"parameters": [
{
"in": "path",
"name": "orgId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/IssueScopedAdminGrantRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/IssueScopedAdminGrantRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/IssueScopedAdminGrantRequest"
}
}
}
},
"responses": {
"201": {
"description": "The issued grant, enveloped as `{ data: {...} }`."
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The scope is empty, the justification is missing, or the policy/expiry is invalid."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The caller is not an administrator of this org."
}
},
"summary": "Issues a scoped-admin grant to a staff member. Under approval policy\r\n`none` the grant activates immediately (and the delegate is notified via the\r\noutbox); under `single-owner` / `dual-owner` it enters the co-sign gate\r\nand appears on other owners' approval worklists.",
"tags": [
"OrgScopedAdminGrants"
]
}
},
"/api/v1/orgs/{orgId}/scoped-admin-grants/mine": {
"get": {
"parameters": [
{
"in": "path",
"name": "orgId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"description": "The delegate's current grant status, enveloped as `{ data: {...} }`."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The caller's token does not belong to this organisation."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The caller holds no scoped-admin grant in this organisation."
}
},
"summary": "The CALLING delegate's own grant lifecycle status — the read behind the\r\ndelegated-admin console's fail-closed gate (2→3 seam, gaps\r\ndebt-2026-08-11-474 / debt-2026-08-11-807).",
"tags": [
"OrgScopedAdminGrants"
]
}
},
"/api/v1/orgs/{orgId}/shared-devices": {
"get": {
"parameters": [
{
"in": "path",
"name": "orgId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/SharedDeviceDto"
},
"type": "array"
}
}
},
"description": "The devices."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The caller does not administer this organisation."
}
},
"summary": "Every device the organisation has enrolled, revoked ones included, newest first.",
"tags": [
"OrgSharedDevices"
]
},
"post": {
"description": "The machine generates an EC P-256 key pair and keeps the private half; only the public\r\nJWK is sent. A JWK carrying `d` is refused.",
"parameters": [
{
"in": "path",
"name": "orgId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/EnrolSharedDeviceRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/EnrolSharedDeviceRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/EnrolSharedDeviceRequest"
}
}
}
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SharedDeviceDto"
}
}
},
"description": "Enrolled."
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The key is not an EC P-256 public JWK (`invalid-key`), or the label is missing."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The caller does not administer this organisation."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Another device already holds this key (`key-already-enrolled`)."
}
},
"summary": "Enrols a machine the organisation owns.",
"tags": [
"OrgSharedDevices"
]
}
},
"/api/v1/orgs/{orgId}/shared-devices/{deviceId}/key": {
"put": {
"description": "The device keeps its id, so captures made before the rotation still name it. The old key stops attesting at once.",
"parameters": [
{
"in": "path",
"name": "orgId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"in": "path",
"name": "deviceId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/RotateSharedDeviceKeyRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/RotateSharedDeviceKeyRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/RotateSharedDeviceKeyRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SharedDeviceDto"
}
}
},
"description": "The device with its new key."
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The key is not an EC P-256 public JWK (`invalid-key`)."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The caller does not administer this organisation."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No such device in this organisation (`shared-device-not-found`)."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The device is revoked (`shared-device-revoked`), or another device holds the key."
}
},
"summary": "Replaces a device's key — after a reimage, or when the old key may be exposed.",
"tags": [
"OrgSharedDevices"
]
}
},
"/api/v1/orgs/{orgId}/shared-devices/{deviceId}/revoke": {
"post": {
"description": "The device never attests again; its row is kept, so what was captured on it stays\r\nattributable. Revoking an already revoked device returns it unchanged.",
"parameters": [
{
"in": "path",
"name": "orgId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"in": "path",
"name": "deviceId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/RevokeSharedDeviceRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/RevokeSharedDeviceRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/RevokeSharedDeviceRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SharedDeviceDto"
}
}
},
"description": "The revoked device."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The caller does not administer this organisation."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No such device in this organisation (`shared-device-not-found`)."
}
},
"summary": "Revokes a device that is decommissioned, sold, lost or stolen. Terminal.",
"tags": [
"OrgSharedDevices"
]
}
},
"/api/v1/principals/users/{userId}": {
"get": {
"parameters": [
{
"description": "The user-principal id to validate.",
"in": "path",
"name": "userId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PrincipalValidationDto"
}
}
},
"description": "The check completed. `exists=false` means no (non-deleted) account resolves to the id;\r\n`exists=true, isActive=false` means the account exists but is deactivated."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No valid bearer token."
}
},
"summary": "Validates that a user principal resolves to a real, active account.",
"tags": [
"Principals"
]
}
},
"/api/v1/probate-role/grants": {
"get": {
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/ProbateRoleGrantDto"
},
"type": "array"
}
}
},
"description": "OK"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
}
},
"summary": "List the Probate Role grants the authenticated partner has assigned.",
"tags": [
"ProbateRole"
]
},
"post": {
"description": "\n\r\n Service principals only (debt-2026-08-25-234). FR-15.009.6 admits a\r\n Probate Role on two preconditions — a verified lifecycle event or a registered PoA\r\n — and neither is a fact this service holds. EstatePlanning does, and it is the only\r\n legitimate caller (`InboundEventConsumers` on PoA activation, and\r\n `ExecutorRenunciationService` after a court-recorded replacement). While this\r\n endpoint accepted a plain `[Authorize]` token, any authenticated user could\r\n POST themselves an Active grant over a stranger's estate — and the grant is not a\r\n bookkeeping row: `ProbateStepUpController` treats it as the role basis for\r\n reaching AAL2, so a self-issued grant was a working key.\r\n\nFollowing the `SafeguardingCasesController` precedent, the authority\r\n model is enforced here even though provisioningEssence.Platform.Infrastructure.Security.RoleClaims.LifecycleServiceAgent onto the EstatePlanning service\r\n account is separate deployment work — so it cannot be bypassed once that lands.\r\n The wire contract already anticipated this: the calling client documents\r\n `401 / 403 → throw (wrong service credential)` and soft-fails the grant\r\n rather than blocking PoA activation, so an unprovisioned token degrades to a\r\n logged, retried re-grant rather than an outage.",
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/GrantProbateRoleRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/GrantProbateRoleRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/GrantProbateRoleRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProbateRoleGrantResponse"
}
}
},
"description": "OK"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden"
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProbateRoleGrantResponse"
}
}
},
"description": "Conflict"
}
},
"summary": "Grant a Probate Role to a fee-earner. Matches the EPIC 15 → EPIC 9 wire\r\ncontract: `200 { grantId }` on create, `409 { grantId }` on an\r\nidempotent re-grant.",
"tags": [
"ProbateRole"
]
}
},
"/api/v1/probate-role/grants/active": {
"get": {
"description": "The authorisation read behind EPIC 15's Probate Dashboard (FR-15.009.2,\r\ndebt-2026-08-25-233). EPIC 9 owns the grant record, so the predicate is answered\r\nhere rather than mirrored into EPIC 15 where it would go stale against a\r\nrevocation. Service-principal gated for the same reason as the grant write: the\r\nanswer names who holds authority over whose estate, which is not a fact an\r\narbitrary authenticated caller may enumerate.",
"parameters": [
{
"in": "query",
"name": "attorneyUserId",
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"in": "query",
"name": "subjectUserId",
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ActiveProbateRoleResult"
}
}
},
"description": "OK"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden"
}
},
"summary": "Does the named attorney currently hold the Probate Role over the named subject?",
"tags": [
"ProbateRole"
]
}
},
"/api/v1/probate-role/grants/{id}/revoke": {
"post": {
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/RevokeProbateRoleRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/RevokeProbateRoleRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/RevokeProbateRoleRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RevokeProbateRoleResult"
}
}
},
"description": "OK"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
}
},
"summary": "Revoke a Probate Role grant before its expiry.",
"tags": [
"ProbateRole"
]
}
},
"/api/v1/profile/name": {
"get": {
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProfileNameResult"
}
}
},
"description": "The stored name and its editability."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No authenticated subject."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The authenticated subject no longer exists."
}
},
"summary": "Returns the holder's stored name and whether they may set it themselves.",
"tags": [
"ProfileName"
]
},
"put": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/SetProfileNameRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/SetProfileNameRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/SetProfileNameRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProfileNameResult"
}
}
},
"description": "The name was set (or already matched)."
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The first name is blank, or a value is too long."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No authenticated subject."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The authenticated subject no longer exists."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "A proofed identity holds the name; use the verified name-change flow."
}
},
"summary": "Sets the holder's first and last name. Setting the stored value again is a no-op.",
"tags": [
"ProfileName"
]
}
},
"/api/v1/profile/preferred-locale": {
"get": {
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PreferredLocaleResult"
}
}
},
"description": "The current preferred-locale state."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No authenticated subject."
}
},
"summary": "Returns the signed-in subject's stored preferred locale (null when unset) and the\r\nsupported locale set for the selector.",
"tags": [
"ProfileLocale"
]
},
"put": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/SetPreferredLocaleRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/SetPreferredLocaleRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/SetPreferredLocaleRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PreferredLocaleResult"
}
}
},
"description": "The preference was set (or already matched)."
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The requested tag is malformed or unsupported."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No authenticated subject."
}
},
"summary": "Sets (or changes) the signed-in subject's preferred communication locale. Idempotent\r\n— re-setting the current value returns 200 with `changed=false` and no event.",
"tags": [
"ProfileLocale"
]
}
},
"/api/v1/proof-of-control/challenges": {
"get": {
"parameters": [
{
"in": "query",
"name": "caseRef",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/OutOfBandProofChallengeView"
},
"type": "array"
}
}
},
"description": "OK"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
}
},
"summary": "Read every challenge raised under one case reference.",
"tags": [
"OutOfBandProof"
]
},
"post": {
"description": "Always returns 201 with a challenge id, whatever the subject turns out to be — an\r\nunknown account, an unverified contact and a reachable account are indistinguishable\r\nin the response, so this endpoint is not an account-existence oracle. An unreachable\r\naccount simply never answers and lapses to `Unresponsive`.",
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/IssueProofChallengeRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/IssueProofChallengeRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/IssueProofChallengeRequest"
}
}
}
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IssueOutOfBandProofChallengeResult"
}
}
},
"description": "Created"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
}
},
"summary": "Issue a challenge to a named account at that account's own recovery address.",
"tags": [
"OutOfBandProof"
]
}
},
"/api/v1/proof-of-control/challenges/{challengeId}": {
"get": {
"parameters": [
{
"in": "path",
"name": "challengeId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OutOfBandProofChallengeView"
}
}
},
"description": "OK"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
}
},
"summary": "Read a challenge's state and the evidence class it currently yields.",
"tags": [
"OutOfBandProof"
]
}
},
"/api/v1/proof-of-control/challenges/{challengeId}/answer": {
"post": {
"description": "\n\r\n Why anonymous. The holder proving control is by definition someone who may\r\n not be able to sign in — that is the whole premise. Requiring a token here would\r\n reintroduce the barrier this capability exists to remove.\r\n \r\n\n\r\n What guards it instead. The challenge id is an unguessable GUID delivered to\r\n nobody, the code is a one-time secret delivered only to the account's own address,\r\n the comparison is constant-time over keyed hashes (SEC-005), and the aggregate caps\r\n wrong answers at `MaxAttempts` before refusing outright. The platform's\r\n `essence-default` IP rate limit (SEC-004) applies on top.\r\n ",
"parameters": [
{
"in": "path",
"name": "challengeId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/AnswerProofChallengeRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/AnswerProofChallengeRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/AnswerProofChallengeRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AnswerOutOfBandProofChallengeResult"
}
}
},
"description": "OK"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Conflict"
}
},
"summary": "Answer a challenge. Deliberately requires NO authenticated session.",
"tags": [
"OutOfBandProof"
]
}
},
"/api/v1/proof-of-control/challenges/{challengeId}/cancel": {
"post": {
"parameters": [
{
"in": "path",
"name": "challengeId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OutOfBandProofChallengeView"
}
}
},
"description": "OK"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
}
},
"summary": "Withdraw an open challenge. Yields `Withdrawn` — no evidence either way.",
"tags": [
"OutOfBandProof"
]
}
},
"/api/v1/proof-of-control/challenges/{challengeId}/extend": {
"post": {
"parameters": [
{
"in": "path",
"name": "challengeId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/ExtendProofChallengeRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExtendProofChallengeRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ExtendProofChallengeRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OutOfBandProofChallengeView"
}
}
},
"description": "OK"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Conflict"
}
},
"summary": "Extend the answer window — the generous-timing control.",
"tags": [
"OutOfBandProof"
]
}
},
"/api/v1/safeguarding-authorities": {
"get": {
"parameters": [
{
"description": "Include bodies whose recognition was withdrawn (audit view).",
"in": "query",
"name": "includeWithdrawn",
"schema": {
"default": false,
"type": "boolean"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/SafeguardingAuthorityRow"
},
"type": "array"
}
}
},
"description": "The register."
}
},
"summary": "The register of recognised safeguarding authorities.",
"tags": [
"SafeguardingAuthorities"
]
},
"post": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/RecogniseSafeguardingAuthorityRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/RecogniseSafeguardingAuthorityRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/RecogniseSafeguardingAuthorityRequest"
}
}
}
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SafeguardingAuthorityRow"
}
}
},
"description": "The body is now recognised and may designate officers."
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The request failed validation."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The organisation already holds a recognition."
}
},
"summary": "Recognises an organisation as a safeguarding authority.",
"tags": [
"SafeguardingAuthorities"
]
}
},
"/api/v1/safeguarding-authorities/{organizationId}/standing": {
"post": {
"parameters": [
{
"in": "path",
"name": "organizationId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/ChangeSafeguardingAuthorityStandingRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/ChangeSafeguardingAuthorityStandingRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ChangeSafeguardingAuthorityStandingRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SafeguardingAuthorityRow"
}
}
},
"description": "The body's updated register row."
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unknown action, or a reason is missing where one is required."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The organisation is not on the register at all."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The transition is not available from the body's current standing."
}
},
"summary": "Suspends, restores or withdraws a body's recognition.",
"tags": [
"SafeguardingAuthorities"
]
}
},
"/api/v1/safeguarding-officers": {
"get": {
"parameters": [
{
"description": "Include revoked designations (the audit view).",
"in": "query",
"name": "includeInactive",
"schema": {
"default": false,
"type": "boolean"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SafeguardingOfficerRegisterResult"
}
}
},
"description": "The register plus its header counts."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No organisation claim, or the organisation is not on the register."
}
},
"summary": "The calling authority's own officer register.",
"tags": [
"SafeguardingOfficers"
]
},
"post": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/DesignateSafeguardingOfficerRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/DesignateSafeguardingOfficerRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/DesignateSafeguardingOfficerRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SafeguardingOfficerRow"
}
}
},
"description": "The officer's register row."
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The request failed validation."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No organisation claim, or the organisation is not a recognised authority."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No account exists for the supplied officer user id."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The authority's recognition is suspended or withdrawn."
}
},
"summary": "Designates an individual onto the calling authority's register, unverified.",
"tags": [
"SafeguardingOfficers"
]
}
},
"/api/v1/safeguarding-officers/directory": {
"get": {
"description": "\n\r\n Gated on the investigator role, not on org administration. The people entitled to see\r\n who may countersign are the people who may ask for a countersignature. Exposing it to org\r\n administrators generally would publish a list of safeguarding officers to every organisation\r\n on the platform.\r\n \r\n\n\r\n The caller is excluded. Dual control means an investigator may never be their own\r\n co-authoriser, so offering themselves would be offering a choice the domain then refuses.\r\n ",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoAuthoriserDirectoryResult"
}
}
},
"description": "The directory."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The caller does not hold the safeguarding-investigator role."
}
},
"summary": "The co-authoriser directory: every currently authorised officer, across every recognised\r\nauthority, minus the caller.",
"tags": [
"SafeguardingOfficers"
]
}
},
"/api/v1/safeguarding-officers/{officerUserId}/standing": {
"post": {
"description": "A revocation is accepted even while the authority's own recognition is suspended: being\r\nunable to withdraw a compromised officer's designation because your recognition lapsed\r\nwould trap a body at exactly the moment it most needs to act.",
"parameters": [
{
"in": "path",
"name": "officerUserId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/ChangeSafeguardingOfficerStandingRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/ChangeSafeguardingOfficerStandingRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ChangeSafeguardingOfficerStandingRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SafeguardingOfficerRow"
}
}
},
"description": "The officer's updated register row."
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unknown action, or a reason is missing where one is required."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No organisation claim, or the organisation is not on the register."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No such officer is on this authority's register."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The transition is unavailable from the current standing."
}
},
"summary": "Stands an officer down, reinstates them, or revokes their designation.",
"tags": [
"SafeguardingOfficers"
]
}
},
"/api/v1/safeguarding-officers/{officerUserId}/verification": {
"post": {
"parameters": [
{
"in": "path",
"name": "officerUserId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/VerifySafeguardingOfficerRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/VerifySafeguardingOfficerRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/VerifySafeguardingOfficerRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SafeguardingOfficerRow"
}
}
},
"description": "The officer's updated register row."
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The request failed validation."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No organisation claim, or the organisation is not a recognised authority."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No such officer is on this authority's register."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The designation has been revoked, or recognition is not in good standing."
}
},
"summary": "Records that the officer's identity has been verified, issuing the\r\n`safeguarding-investigator` claim and adding them to the co-authoriser directory.",
"tags": [
"SafeguardingOfficers"
]
}
},
"/api/v1/sessions": {
"delete": {
"parameters": [
{
"description": "If true, keeps the current session active. Default is true.",
"in": "query",
"name": "KeepCurrent",
"schema": {
"type": "boolean"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RevokeAllSessionsResult"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/RevokeAllSessionsResult"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/RevokeAllSessionsResult"
}
}
},
"description": "OK"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
}
},
"summary": "Revoke all sessions except the current one (logout from all other devices)",
"tags": [
"Sessions"
]
},
"get": {
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/SessionDto"
},
"type": "array"
}
},
"text/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/SessionDto"
},
"type": "array"
}
},
"text/plain": {
"schema": {
"items": {
"$ref": "#/components/schemas/SessionDto"
},
"type": "array"
}
}
},
"description": "OK"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
}
},
"summary": "Get all sessions for the authenticated user",
"tags": [
"Sessions"
]
}
},
"/api/v1/sessions/current/operating-jurisdiction": {
"delete": {
"description": "The session's next token carries no `operating_jurisdiction`; a token already issued\r\nruns to its own expiry. Needs no step-up: it can only remove the claim.",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OperatingJurisdictionEndedResponse"
}
}
},
"description": "Ended."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No such session, or it has no declaration in force (`no-operating-jurisdiction`)."
}
},
"summary": "Ends this session's declaration before its period runs out.",
"tags": [
"SessionOperatingJurisdiction"
]
},
"put": {
"description": "Requires a fresh (≤ 5 minutes) `act=operating-jurisdiction-declaration` elevation on\r\n`X-Step-Up-Token`, proved with a passkey, an authenticator-app code or a text-message\r\ncode. Checked before anything is read, so a refusal says nothing about the value. A later\r\ndeclaration replaces an earlier one and starts a new period.",
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/DeclareOperatingJurisdictionRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeclareOperatingJurisdictionRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/DeclareOperatingJurisdictionRequest"
}
}
},
"description": "The declared ISO 3166-1 alpha-2 code."
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OperatingJurisdictionResponse"
}
}
},
"description": "Recorded; the session's next token carries it until `expiresAt`."
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No acceptable step-up elevation (`step-up-required`)."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Conflict"
}
},
"summary": "Declares the jurisdiction the caller is working from, for this session.",
"tags": [
"SessionOperatingJurisdiction"
]
}
},
"/api/v1/sessions/wearable/revoke": {
"post": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/RevokeWearableSessionRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/RevokeWearableSessionRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/RevokeWearableSessionRequest"
}
}
},
"description": "The watch device and reason for revocation."
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RevokeWearableSessionResult"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/RevokeWearableSessionResult"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/RevokeWearableSessionResult"
}
}
},
"description": "OK"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
}
},
"summary": "Scope-revoke a single lost companion watch's delegated session (journey\r\n`lost-wearable-delegated-session-revoke`). Revokes ONLY the named watch's delegated\r\nJWT — 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)\r\n/ FR-09.013). The delegated token is added to the revocation list so a found watch is\r\nprovably inert immediately (`boundedInertBy`), and a durable\r\n`WearableSessionRevokedIntegrationEvent` is emitted on the outbox for incident audit.\r\nThis is a safety action and is not billing-gated.",
"tags": [
"Sessions"
]
}
},
"/api/v1/sessions/{id}": {
"delete": {
"parameters": [
{
"description": "Session ID to revoke",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RevokeSessionResult"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/RevokeSessionResult"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/RevokeSessionResult"
}
}
},
"description": "OK"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
}
},
"summary": "Revoke a specific session (logout from that session)",
"tags": [
"Sessions"
]
},
"get": {
"parameters": [
{
"description": "Session ID",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SessionDto"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/SessionDto"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/SessionDto"
}
}
},
"description": "OK"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
}
},
"summary": "Get a specific session by ID",
"tags": [
"Sessions"
]
}
},
"/api/v1/subject-export-delegation": {
"post": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/SubjectExportDelegationRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/SubjectExportDelegationRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/SubjectExportDelegationRequest"
}
}
},
"description": "The export it is bound to and the lifetime its SLA needs."
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SubjectExportDelegationResponse"
}
}
},
"description": "OK"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
}
},
"summary": "Mint a delegation credential for the authenticated caller, bound to one queued export.",
"tags": [
"SubjectExportDelegation"
]
}
},
"/api/v1/users/me/locale": {
"get": {
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PreferredLocaleResult"
}
}
},
"description": "The current preferred-locale state."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No authenticated subject."
}
},
"summary": "Returns the signed-in subject's stored preferred locale (null when unset) and the\r\nsupported locale set for the selector.",
"tags": [
"ProfileLocale"
]
},
"put": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/SetPreferredLocaleRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/SetPreferredLocaleRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/SetPreferredLocaleRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PreferredLocaleResult"
}
}
},
"description": "The preference was set (or already matched)."
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The requested tag is malformed or unsupported."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No authenticated subject."
}
},
"summary": "Sets (or changes) the signed-in subject's preferred communication locale. Idempotent\r\n— re-setting the current value returns 200 with `changed=false` and no event.",
"tags": [
"ProfileLocale"
]
}
},
"/api/v1/users/me/protection-status": {
"get": {
"description": "DVS-4.4g: a session opened with the alternate credential gets the 404. Every component of this\r\n read model belongs to the same protection (the alternate passphrase, the backup view it opens, the\r\n trusted contact it alerts), so any of them would tell whoever holds that session that the protection\r\n exists. The session is answered exactly as an account that has set up nothing, by the same\r\n `NotFound()` on the same path, decided on the server from the session's sign-in tag — not left to\r\n the web panel hiding itself. The read still runs, so the two answers cost the same.",
"responses": {
"200": {
"description": "OK"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
}
},
"summary": "Returns the authenticated owner's aggregated protection status, or 404 when nothing has been\r\nprovisioned yet (the client renders a neutral \"not set up yet\" state on absence).",
"tags": [
"ProtectionStatus"
]
}
},
"/api/v1/users/me/protection-status/alternate-credential": {
"delete": {
"description": "DVS-4.4f: deliberately NOT gated. Withdrawing removes a way in; it lowers no sign-in or\r\n recovery path, so it is not the threat P-31 and P-37 answer. A step-up does nothing against a\r\n coercer standing over the holder (they can make the holder complete it), and a holder who has\r\n lost their factor must still be able to remove one someone else planted. A withdrawal the holder\r\n did not make does matter to them, so it raises the same neutral holder alert as enrolment, on\r\n both channels (P-26).\r\n \nDVS-4.4g: a session opened with the alternate credential cannot withdraw it. It gets the\r\n `204` an account with none gets, and nothing changes and nothing is announced — as for an account\r\n with none — while the handler reads, saves and logs as for any other call\r\n (Essence.Identity.Auth.Application.Commands.ProtectionStatus.WithdrawDuressCredentialCommand.FromAlternateCredentialSession). Otherwise the\r\n withdrawal alert in that session's own inbox would tell a coercer that a credential existed, and the\r\n session the protection exists for could disarm it.",
"responses": {
"204": {
"description": "No Content"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
}
},
"summary": "Withdraws the owner's alternate credential. Idempotent: 204 whether or not one was\r\nenrolled, so the response never reveals whether the account had one.",
"tags": [
"ProtectionStatus"
]
},
"put": {
"description": "\nOwner-scoped like every route on this controller: the subject comes from the JWT,\r\n so no caller can enrol an alternate credential onto someone else's account — which\r\n would otherwise be a backdoor into another person's sign-in.\r\n\n\r\n DVS-4.4f: a fresh step-up first.\r\n `LoginCommandHandler` accepts this\r\n credential as a sign-in password, so setting it is adding an authenticator (P-31): it needs\r\n a fresh (at most 5 minutes) `act=authenticator-enrolment` elevation on\r\n `X-Step-Up-Token`, proved at the account's own level (a passkey, authenticator-app or\r\n text-message code when it has one, else its password, P-23; never an emailed or backup code),\r\n with the P-32 exception for a federated-only account. Without it a stolen session could plant\r\n a sign-in password of its own choosing that outlives the session. The gate runs before the\r\n credential is read or hashed, and is staged with the other DVS-4.4 gates\r\n (`Auth:AuthenticatorEnrolmentStepUp:Enabled`, P-18). An enrolment raises the holder's\r\n neutral \"a sign-in setting was changed\" alert on both channels (DVS-7.4b path).",
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/EnrolAlternateCredentialRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/EnrolAlternateCredentialRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/EnrolAlternateCredentialRequest"
}
}
}
},
"responses": {
"204": {
"description": "No Content"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Conflict"
}
},
"summary": "Enrols (or replaces) the owner's ALTERNATE credential — the second proof the cold\r\nsign-in accepts, for the `duress-passphrase-silent-alarm-and-decoy-unlock`\r\njourney (debt-2026-08-10-001).",
"tags": [
"ProtectionStatus"
]
}
},
"/api/v1/users/me/protection-status/trusted-contact/reinvite": {
"post": {
"responses": {
"202": {
"description": "Accepted"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
}
},
"summary": "Re-invites (or re-picks) the owner's trusted contact after their consent lapsed or was\r\nrevoked. Best-effort: emits the re-invite event for EPIC 66 to dispatch and returns 202.",
"tags": [
"ProtectionStatus"
]
}
},
"/api/v1/webauthn/authenticate/begin": {
"post": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/BeginWebAuthnAuthenticationRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/BeginWebAuthnAuthenticationRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/BeginWebAuthnAuthenticationRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebAuthnAuthenticationOptions"
}
}
},
"description": "Authentication options returned"
}
},
"summary": "Begins a WebAuthn authentication ceremony. Returns credential request options\r\nincluding a challenge for the client to pass to navigator.credentials.get().\r\nSupports both identified (user known) and discoverable (passkey) flows.",
"tags": [
"WebAuthn"
]
}
},
"/api/v1/webauthn/authenticate/complete": {
"post": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/CompleteWebAuthnAuthenticationRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/CompleteWebAuthnAuthenticationRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/CompleteWebAuthnAuthenticationRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebAuthnAuthenticationResult"
}
}
},
"description": "Authentication successful, tokens returned"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Assertion verification failed"
}
},
"summary": "Completes a WebAuthn authentication ceremony. Verifies the assertion\r\nresponse and issues authentication tokens on success.",
"tags": [
"WebAuthn"
]
}
},
"/api/v1/webauthn/credentials": {
"get": {
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebAuthnCredentialListResponse"
}
}
},
"description": "Enrolled passkeys returned."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "User not authenticated."
}
},
"summary": "Lists the calling user's active passkeys for the Security-settings\r\nmanagement surface. Returns an envelope `{ data: [...] }`.",
"tags": [
"WebAuthn"
]
}
},
"/api/v1/webauthn/credentials/{id}": {
"delete": {
"description": "Requires a fresh (≤ 5 minutes) GPG 44 medium step-up elevation, `act=passkey-removal`, on\r\n`X-Step-Up-Token` (Essence.Identity.Auth.Api.Security.IPasskeyRemovalStepUpGate; DVS-4.4, TF 1.0 §7.3.1.c):\r\nremoving a way to sign in is not something a bearer session alone may do. Checked before the\r\ncredential is looked up, so a refusal says nothing about which passkeys exist.",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"204": {
"description": "Credential removed."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No acceptable step-up elevation (`step-up-required`, or `step-up-resource-mismatch`)."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Credential not found or not owned by the caller."
}
},
"summary": "Removes (deactivates) one of the calling user's passkeys.",
"tags": [
"WebAuthn"
]
},
"patch": {
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/RenameWebAuthnCredentialRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/RenameWebAuthnCredentialRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/RenameWebAuthnCredentialRequest"
}
}
}
},
"responses": {
"204": {
"description": "Credential renamed."
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid name."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Credential not found or not owned by the caller."
}
},
"summary": "Renames one of the calling user's passkeys.",
"tags": [
"WebAuthn"
]
}
},
"/api/v1/webauthn/login/complete": {
"post": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/CompleteWebAuthnAuthenticationRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/CompleteWebAuthnAuthenticationRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/CompleteWebAuthnAuthenticationRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebAuthnAuthenticationResult"
}
}
},
"description": "Authentication successful, tokens returned"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Assertion verification failed"
}
},
"summary": "Completes a WebAuthn authentication ceremony. Verifies the assertion\r\nresponse and issues authentication tokens on success.",
"tags": [
"WebAuthn"
]
}
},
"/api/v1/webauthn/login/options": {
"post": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/BeginWebAuthnAuthenticationRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/BeginWebAuthnAuthenticationRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/BeginWebAuthnAuthenticationRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebAuthnAuthenticationOptions"
}
}
},
"description": "Authentication options returned"
}
},
"summary": "Begins a WebAuthn authentication ceremony. Returns credential request options\r\nincluding a challenge for the client to pass to navigator.credentials.get().\r\nSupports both identified (user known) and discoverable (passkey) flows.",
"tags": [
"WebAuthn"
]
}
},
"/api/v1/webauthn/passwordless/challenge": {
"post": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/PasswordlessLoginChallengeRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/PasswordlessLoginChallengeRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/PasswordlessLoginChallengeRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PasswordlessLoginChallengeResult"
}
}
},
"description": "Challenge issued"
}
},
"summary": "Issues a passwordless WebAuthn challenge with an EMPTY\r\n`allowCredentials` list so the authenticator picks a\r\ndiscoverable credential (passkey). No username is collected at\r\nthis step; the user is identified by the `userHandle` the\r\nauthenticator returns at login time.",
"tags": [
"WebAuthn"
]
}
},
"/api/v1/webauthn/passwordless/login": {
"post": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/PasswordlessLoginRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/PasswordlessLoginRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/PasswordlessLoginRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PasswordlessLoginResult"
}
}
},
"description": "Login successful, tokens returned"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Verification failed"
}
},
"summary": "Completes a passwordless WebAuthn login by verifying the\r\nassertion against the credential identified by the supplied\r\n`userHandle`. On success returns full authentication\r\ntokens — this is a primary-factor login, no password involved.",
"tags": [
"WebAuthn"
]
}
},
"/api/v1/webauthn/register/begin": {
"post": {
"description": "Requires a fresh (≤ 5 minutes) `act=authenticator-enrolment` elevation on\r\n`X-Step-Up-Token`, proved with a factor the account already has (DVS-4.4b): otherwise a\r\nbearer session alone could add its own passkey and then pass every other step-up with it.",
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/BeginWebAuthnRegistrationRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/BeginWebAuthnRegistrationRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/BeginWebAuthnRegistrationRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebAuthnRegistrationOptions"
}
}
},
"description": "Registration options returned"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "User not authenticated, or no acceptable step-up elevation (`step-up-required`)"
}
},
"summary": "Begins a WebAuthn registration ceremony. Returns credential creation options\r\nincluding a challenge for the client to pass to navigator.credentials.create().",
"tags": [
"WebAuthn"
]
}
},
"/api/v1/webauthn/register/complete": {
"post": {
"description": "Requires the same fresh `act=authenticator-enrolment` elevation as `register/begin`\r\n(DVS-4.4b), so a ceremony begun with one cannot be finished after it has gone stale.",
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/CompleteWebAuthnRegistrationRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/CompleteWebAuthnRegistrationRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/CompleteWebAuthnRegistrationRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebAuthnRegistrationResult"
}
}
},
"description": "Credential registered successfully"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Attestation verification failed"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No acceptable step-up elevation (`step-up-required`)"
}
},
"summary": "Completes a WebAuthn registration ceremony. Verifies the attestation\r\nresponse from the authenticator and stores the credential.",
"tags": [
"WebAuthn"
]
}
},
"/api/v1/webauthn/register/options": {
"post": {
"description": "Requires a fresh (≤ 5 minutes) `act=authenticator-enrolment` elevation on\r\n`X-Step-Up-Token`, proved with a factor the account already has (DVS-4.4b): otherwise a\r\nbearer session alone could add its own passkey and then pass every other step-up with it.",
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/BeginWebAuthnRegistrationRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/BeginWebAuthnRegistrationRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/BeginWebAuthnRegistrationRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebAuthnRegistrationOptions"
}
}
},
"description": "Registration options returned"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "User not authenticated, or no acceptable step-up elevation (`step-up-required`)"
}
},
"summary": "Begins a WebAuthn registration ceremony. Returns credential creation options\r\nincluding a challenge for the client to pass to navigator.credentials.create().",
"tags": [
"WebAuthn"
]
}
}
},
"security": [
{
"Bearer": []
}
]
}