{
"components": {
"schemas": {
"CreateRecoveryConfigurationRequest": {
"additionalProperties": false,
"properties": {
"schemeType": {
"nullable": true,
"type": "string"
},
"threshold": {
"format": "int32",
"type": "integer"
},
"totalShares": {
"format": "int32",
"type": "integer"
}
},
"type": "object"
},
"EnrolGuardianAttestationKeyRequest": {
"additionalProperties": false,
"properties": {
"attestationPublicKey": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"GenerateSharesRequest": {
"additionalProperties": false,
"properties": {
"recoveryConfigurationId": {
"format": "uuid",
"type": "string"
},
"shareMetadata": {
"items": {
"$ref": "#/components/schemas/ShareMetadataInput"
},
"nullable": true,
"type": "array"
}
},
"type": "object"
},
"GenerateSharesResponse": {
"additionalProperties": false,
"properties": {
"recoveryConfigurationId": {
"format": "uuid",
"type": "string"
},
"shareMetadata": {
"items": {
"$ref": "#/components/schemas/ShareMetadataDto"
},
"nullable": true,
"type": "array"
},
"sharesCreated": {
"format": "int32",
"type": "integer"
}
},
"type": "object"
},
"GuardianAttestationChallengeResponse": {
"additionalProperties": false,
"properties": {
"challengeNonce": {
"nullable": true,
"type": "string"
},
"expiresAt": {
"format": "date-time",
"type": "string"
},
"purpose": {
"nullable": true,
"type": "string"
},
"token": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"GuardianAttestationResultResponse": {
"additionalProperties": false,
"properties": {
"nextAttestationDueAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"verified": {
"type": "boolean"
}
},
"type": "object"
},
"GuardianInvitationContextResponse": {
"additionalProperties": false,
"properties": {
"configurationId": {
"format": "uuid",
"type": "string"
},
"expiresAt": {
"format": "date-time",
"type": "string"
},
"guardianDisplayName": {
"nullable": true,
"type": "string"
},
"guardianIdentity": {
"nullable": true,
"type": "string"
},
"invitationStatus": {
"nullable": true,
"type": "string"
},
"nominatedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"otherGuardiansCount": {
"format": "int32",
"type": "integer"
},
"requesterDisplayName": {
"nullable": true,
"type": "string"
},
"requesterUserId": {
"format": "uuid",
"type": "string"
},
"shareIndex": {
"format": "int32",
"type": "integer"
},
"threshold": {
"format": "int32",
"type": "integer"
},
"totalShares": {
"format": "int32",
"type": "integer"
}
},
"type": "object"
},
"GuardianRecoveryContextResponse": {
"additionalProperties": false,
"properties": {
"guardianIdentity": {
"nullable": true,
"type": "string"
},
"initiatedAt": {
"format": "date-time",
"type": "string"
},
"recoveryAttemptId": {
"format": "uuid",
"type": "string"
},
"recoveryTransportPublicKeyJwk": {
"$ref": "#/components/schemas/RsaPublicKeyJwk"
},
"requesterDisplayName": {
"nullable": true,
"type": "string"
},
"shareIndex": {
"format": "int32",
"type": "integer"
},
"submittedByContactId": {
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"InitiateRecoveryRequest": {
"additionalProperties": false,
"properties": {
"guardianQuorumId": {
"format": "uuid",
"nullable": true,
"type": "string"
},
"recoveryConfigurationId": {
"format": "uuid",
"type": "string"
},
"recoveryTransportPublicKey": {
"nullable": true,
"type": "string"
},
"requestGuardianQuorum": {
"type": "boolean"
},
"stepUpToken": {
"nullable": true,
"type": "string"
},
"withdrawGuardianQuorumId": {
"format": "uuid",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"NominateRecoveryContactsRequest": {
"additionalProperties": false,
"properties": {
"contacts": {
"items": {
"$ref": "#/components/schemas/RecoveryContactNominationInput"
},
"nullable": true,
"type": "array"
},
"schemeType": {
"nullable": true,
"type": "string"
},
"threshold": {
"format": "int32",
"type": "integer"
},
"totalShares": {
"format": "int32",
"type": "integer"
}
},
"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"
},
"PromoteRedistributedRecoveryConfigurationRequest": {
"additionalProperties": false,
"properties": {
"establishedShareCount": {
"format": "int32",
"type": "integer"
},
"newConfigurationId": {
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"PromoteRedistributedRecoveryConfigurationResult": {
"additionalProperties": false,
"properties": {
"activeConfigurationId": {
"format": "uuid",
"type": "string"
},
"establishedShareCount": {
"format": "int32",
"type": "integer"
},
"invalidatedConfigurationId": {
"format": "uuid",
"type": "string"
},
"newConfigurationId": {
"format": "uuid",
"type": "string"
},
"swapped": {
"type": "boolean"
},
"threshold": {
"format": "int32",
"type": "integer"
},
"userId": {
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"ReconstructSecretRequest": {
"additionalProperties": false,
"properties": {
"confirm": {
"type": "boolean"
},
"recoveringDeviceFingerprint": {
"nullable": true,
"type": "string"
},
"recoveryAttemptId": {
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"ReconstructSecretResponse": {
"additionalProperties": false,
"properties": {
"accessToken": {
"nullable": true,
"type": "string"
},
"alreadyConfirmed": {
"type": "boolean"
},
"completedAt": {
"format": "date-time",
"type": "string"
},
"confirmed": {
"type": "boolean"
},
"recoveryAttemptId": {
"format": "uuid",
"type": "string"
},
"refreshToken": {
"nullable": true,
"type": "string"
},
"refreshTokenExpiresAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"sessionExpiresAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"shares": {
"items": {
"$ref": "#/components/schemas/SubmittedShareDto"
},
"nullable": true,
"type": "array"
},
"sharesHeld": {
"type": "boolean"
},
"sharesReturned": {
"format": "int32",
"type": "integer"
},
"success": {
"type": "boolean"
}
},
"type": "object"
},
"RecoveryAttemptResponse": {
"additionalProperties": false,
"properties": {
"anchorConfirmed": {
"nullable": true,
"type": "boolean"
},
"assuranceLevel": {
"nullable": true,
"type": "string"
},
"completedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"hasSufficientShares": {
"type": "boolean"
},
"id": {
"format": "uuid",
"type": "string"
},
"initiatedAt": {
"format": "date-time",
"type": "string"
},
"ipAddress": {
"nullable": true,
"type": "string"
},
"recoveryConfigurationId": {
"format": "uuid",
"type": "string"
},
"recoveryTransportPublicKey": {
"nullable": true,
"type": "string"
},
"relayedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"sharesHeld": {
"type": "boolean"
},
"sharesSubmitted": {
"format": "int32",
"type": "integer"
},
"status": {
"nullable": true,
"type": "string"
},
"thresholdRequired": {
"format": "int32",
"type": "integer"
},
"userAgent": {
"nullable": true,
"type": "string"
},
"userId": {
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"RecoveryAuditChainPrefixResponse": {
"additionalProperties": false,
"properties": {
"anchorEntryId": {
"format": "uuid",
"type": "string"
},
"declaredAt": {
"format": "date-time",
"type": "string"
},
"declaredEntries": {
"format": "int32",
"nullable": true,
"type": "integer"
},
"entriesBeforeAnchor": {
"format": "int32",
"type": "integer"
},
"reason": {
"nullable": true,
"type": "string"
},
"verdict": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"RecoveryAuditChainVerificationResponse": {
"additionalProperties": false,
"properties": {
"entriesChecked": {
"format": "int32",
"type": "integer"
},
"failureReason": {
"nullable": true,
"type": "string"
},
"firstFailureEntryId": {
"format": "uuid",
"nullable": true,
"type": "string"
},
"firstFailureIndex": {
"format": "int32",
"nullable": true,
"type": "integer"
},
"isValid": {
"type": "boolean"
},
"prefix": {
"$ref": "#/components/schemas/RecoveryAuditChainPrefixResponse"
}
},
"type": "object"
},
"RecoveryConfigurationResolutionResponse": {
"additionalProperties": false,
"properties": {
"recoveryConfigurationId": {
"format": "uuid",
"nullable": true,
"type": "string"
},
"resolved": {
"type": "boolean"
}
},
"type": "object"
},
"RecoveryConfigurationResponse": {
"additionalProperties": false,
"properties": {
"acceptedContactCount": {
"format": "int32",
"type": "integer"
},
"contacts": {
"items": {
"$ref": "#/components/schemas/RecoveryContactStateDto"
},
"nullable": true,
"type": "array"
},
"createdAt": {
"format": "date-time",
"type": "string"
},
"declinedContactCount": {
"format": "int32",
"type": "integer"
},
"establishedShareCount": {
"format": "int32",
"type": "integer"
},
"id": {
"format": "uuid",
"type": "string"
},
"isActive": {
"type": "boolean"
},
"lastUpdatedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"nominatedContactCount": {
"format": "int32",
"type": "integer"
},
"pendingContactCount": {
"format": "int32",
"type": "integer"
},
"schemeType": {
"nullable": true,
"type": "string"
},
"shareMetadata": {
"items": {
"$ref": "#/components/schemas/ShareMetadataDto"
},
"nullable": true,
"type": "array"
},
"state": {
"nullable": true,
"type": "string"
},
"threshold": {
"format": "int32",
"type": "integer"
},
"totalShares": {
"format": "int32",
"type": "integer"
},
"usableShareCount": {
"format": "int32",
"type": "integer"
},
"userId": {
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"RecoveryContactNominationInput": {
"additionalProperties": false,
"properties": {
"distributionMethod": {
"nullable": true,
"type": "string"
},
"email": {
"nullable": true,
"type": "string"
},
"essenceAccountId": {
"format": "uuid",
"nullable": true,
"type": "string"
},
"name": {
"nullable": true,
"type": "string"
},
"phone": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"RecoveryContactNominationResponse": {
"additionalProperties": false,
"properties": {
"configurationId": {
"format": "uuid",
"type": "string"
},
"invitationsSentAtIso": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"nominations": {
"items": {
"$ref": "#/components/schemas/RecoveryContactNominationState"
},
"nullable": true,
"type": "array"
},
"scheme": {
"nullable": true,
"type": "string"
},
"threshold": {
"format": "int32",
"type": "integer"
},
"totalShares": {
"format": "int32",
"type": "integer"
}
},
"type": "object"
},
"RecoveryContactNominationState": {
"additionalProperties": false,
"properties": {
"awaitingShareGeneration": {
"type": "boolean"
},
"email": {
"nullable": true,
"type": "string"
},
"guardianIdentityType": {
"nullable": true,
"type": "string"
},
"invitationDispatchedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"invitationStatus": {
"nullable": true,
"type": "string"
},
"name": {
"nullable": true,
"type": "string"
},
"shareIndex": {
"format": "int32",
"type": "integer"
},
"shareMetadataId": {
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"RecoveryContactStateDto": {
"additionalProperties": false,
"properties": {
"accepted": {
"type": "boolean"
},
"awaitingShareGeneration": {
"type": "boolean"
},
"canContributeToRecovery": {
"type": "boolean"
},
"contactEmail": {
"nullable": true,
"type": "string"
},
"displayName": {
"nullable": true,
"type": "string"
},
"guardianIdentityType": {
"nullable": true,
"type": "string"
},
"invitationDispatched": {
"type": "boolean"
},
"invitationStatus": {
"nullable": true,
"type": "string"
},
"isInvalidated": {
"type": "boolean"
},
"linkedEssenceAccountId": {
"format": "uuid",
"nullable": true,
"type": "string"
},
"nominatedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"respondedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"shareIndexes": {
"items": {
"format": "int32",
"type": "integer"
},
"nullable": true,
"type": "array"
}
},
"type": "object"
},
"RecoveryCustodyPostureResult": {
"additionalProperties": false,
"properties": {
"hasSurvivingConfiguration": {
"type": "boolean"
},
"userId": {
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"RecoveryDryRunResponse": {
"additionalProperties": false,
"properties": {
"concludedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"expiresAt": {
"format": "date-time",
"type": "string"
},
"guardiansAsked": {
"format": "int32",
"type": "integer"
},
"guardiansResponded": {
"format": "int32",
"type": "integer"
},
"initiatedAt": {
"format": "date-time",
"type": "string"
},
"noSecretReconstructed": {
"type": "boolean"
},
"outcome": {
"nullable": true,
"type": "string"
},
"rehearsalId": {
"format": "uuid",
"type": "string"
},
"thresholdRequired": {
"format": "int32",
"type": "integer"
},
"verdictMeaning": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"RecoveryEnrolmentPosture": {
"additionalProperties": false,
"properties": {
"guardianCount": {
"format": "int32",
"type": "integer"
},
"guardianRecentlyDeparted": {
"type": "boolean"
},
"lastAttestationAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"thresholdRequired": {
"format": "int32",
"type": "integer"
},
"userRef": {
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"RecoveryEnrolmentPostureLookupRequest": {
"additionalProperties": false,
"properties": {
"userRefs": {
"items": {
"format": "uuid",
"type": "string"
},
"nullable": true,
"type": "array"
}
},
"type": "object"
},
"RecoveryGuardianLink": {
"additionalProperties": false,
"properties": {
"alreadyBelowThreshold": {
"type": "boolean"
},
"guardianRef": {
"format": "uuid",
"type": "string"
},
"userRef": {
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"RecoveryGuardianLinkLookupRequest": {
"additionalProperties": false,
"properties": {
"guardianRefs": {
"items": {
"format": "uuid",
"type": "string"
},
"nullable": true,
"type": "array"
},
"userRefs": {
"items": {
"format": "uuid",
"type": "string"
},
"nullable": true,
"type": "array"
}
},
"type": "object"
},
"RecoveryInitiationQuorumResponse": {
"additionalProperties": false,
"properties": {
"expiresAt": {
"format": "date-time",
"type": "string"
},
"guardiansAsked": {
"format": "int32",
"type": "integer"
},
"guardiansConfirmed": {
"format": "int32",
"type": "integer"
},
"id": {
"format": "uuid",
"type": "string"
},
"recoveryAttemptId": {
"format": "uuid",
"nullable": true,
"type": "string"
},
"recoveryConfigurationId": {
"format": "uuid",
"type": "string"
},
"requestedAt": {
"format": "date-time",
"type": "string"
},
"status": {
"nullable": true,
"type": "string"
},
"thresholdMet": {
"type": "boolean"
},
"thresholdRequired": {
"format": "int32",
"type": "integer"
}
},
"type": "object"
},
"RecoveryLifecycleEvent": {
"additionalProperties": false,
"properties": {
"id": {
"format": "uuid",
"type": "string"
},
"occurredAt": {
"format": "date-time",
"type": "string"
},
"outcome": {
"nullable": true,
"type": "string"
},
"type": {
"nullable": true,
"type": "string"
},
"userRef": {
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"RecoveryLifecycleEventLookupRequest": {
"additionalProperties": false,
"properties": {
"from": {
"format": "date-time",
"type": "string"
},
"until": {
"format": "date-time",
"type": "string"
},
"userRefs": {
"items": {
"format": "uuid",
"type": "string"
},
"nullable": true,
"type": "array"
}
},
"type": "object"
},
"RegisterRedistributedRecoveryConfigurationRequest": {
"additionalProperties": false,
"properties": {
"schemeType": {
"nullable": true,
"type": "string"
},
"threshold": {
"format": "int32",
"type": "integer"
},
"totalShares": {
"format": "int32",
"type": "integer"
}
},
"type": "object"
},
"RehearseReconstructionRequest": {
"additionalProperties": false,
"properties": {
"recoveryAttemptId": {
"format": "uuid",
"type": "string"
},
"simulatedActorType": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"RehearseReconstructionResponse": {
"additionalProperties": false,
"properties": {
"noDataReleased": {
"type": "boolean"
},
"noUmkUnwrapped": {
"type": "boolean"
},
"rehearsalSessionId": {
"format": "uuid",
"type": "string"
},
"rehearsedAt": {
"format": "date-time",
"type": "string"
},
"runType": {
"nullable": true,
"type": "string"
},
"sharesAvailable": {
"format": "int32",
"type": "integer"
},
"sharesRequired": {
"format": "int32",
"type": "integer"
},
"simulatedActorType": {
"nullable": true,
"type": "string"
},
"wouldReconstruct": {
"type": "boolean"
}
},
"type": "object"
},
"ResolveRecoveryConfigurationRequest": {
"additionalProperties": false,
"properties": {
"accountEmail": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"RespondToGuardianInvitationRequest": {
"additionalProperties": false,
"properties": {
"accepted": {
"type": "boolean"
},
"guardianIdentity": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"RespondToGuardianInvitationResponse": {
"additionalProperties": false,
"properties": {
"accepted": {
"type": "boolean"
},
"configurationId": {
"format": "uuid",
"type": "string"
},
"guardianIdentity": {
"nullable": true,
"type": "string"
},
"sharesAffected": {
"format": "int32",
"type": "integer"
}
},
"type": "object"
},
"RsaPublicKeyJwk": {
"additionalProperties": false,
"properties": {
"alg": {
"nullable": true,
"type": "string"
},
"e": {
"nullable": true,
"type": "string"
},
"ext": {
"type": "boolean"
},
"key_ops": {
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
},
"kty": {
"nullable": true,
"type": "string"
},
"n": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"SelfServiceRecoveryLinkRequest": {
"additionalProperties": false,
"properties": {
"organizationId": {
"format": "uuid",
"type": "string"
},
"userRef": {
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"SelfServiceRecoveryLinkResponse": {
"additionalProperties": false,
"properties": {
"sent": {
"type": "boolean"
}
},
"type": "object"
},
"ShareCollectionStatusResponse": {
"additionalProperties": false,
"properties": {
"canReconstruct": {
"type": "boolean"
},
"pendingShareIndices": {
"items": {
"format": "int32",
"type": "integer"
},
"nullable": true,
"type": "array"
},
"recoveryAttemptId": {
"format": "uuid",
"type": "string"
},
"sharesSubmitted": {
"format": "int32",
"type": "integer"
},
"status": {
"nullable": true,
"type": "string"
},
"submittedShareIndices": {
"items": {
"format": "int32",
"type": "integer"
},
"nullable": true,
"type": "array"
},
"thresholdRequired": {
"format": "int32",
"type": "integer"
},
"totalShares": {
"format": "int32",
"type": "integer"
}
},
"type": "object"
},
"ShareMetadataDto": {
"additionalProperties": false,
"properties": {
"attestationDueAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"attestationFailureCause": {
"nullable": true,
"type": "string"
},
"attestationLastVerifiedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"attestationStatus": {
"nullable": true,
"type": "string"
},
"contactEmail": {
"nullable": true,
"type": "string"
},
"contactPhone": {
"nullable": true,
"type": "string"
},
"displayName": {
"nullable": true,
"type": "string"
},
"distributedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"distributionConfirmationId": {
"nullable": true,
"type": "string"
},
"distributionMethod": {
"nullable": true,
"type": "string"
},
"guardianIdentityType": {
"nullable": true,
"type": "string"
},
"id": {
"format": "uuid",
"type": "string"
},
"invitationRespondedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"invitationStatus": {
"nullable": true,
"type": "string"
},
"isAttestationEnrolled": {
"type": "boolean"
},
"isAwaitingShareGeneration": {
"type": "boolean"
},
"isDistributed": {
"type": "boolean"
},
"isInvalidated": {
"type": "boolean"
},
"isInvitationAccepted": {
"type": "boolean"
},
"isUsable": {
"type": "boolean"
},
"linkedEssenceAccountId": {
"format": "uuid",
"nullable": true,
"type": "string"
},
"recoveryConfigurationId": {
"format": "uuid",
"type": "string"
},
"shareChecksum": {
"nullable": true,
"type": "string"
},
"shareIndex": {
"format": "int32",
"type": "integer"
}
},
"type": "object"
},
"ShareMetadataInput": {
"additionalProperties": false,
"properties": {
"contactEmail": {
"nullable": true,
"type": "string"
},
"contactPhone": {
"nullable": true,
"type": "string"
},
"distributionMethod": {
"nullable": true,
"type": "string"
},
"linkedEssenceAccountId": {
"format": "uuid",
"type": "string"
},
"shareChecksum": {
"nullable": true,
"type": "string"
},
"shareIndex": {
"format": "int32",
"type": "integer"
}
},
"type": "object"
},
"ShareVerificationResponse": {
"additionalProperties": false,
"properties": {
"failureReason": {
"nullable": true,
"type": "string"
},
"isValid": {
"type": "boolean"
},
"linkedEssenceAccountId": {
"format": "uuid",
"nullable": true,
"type": "string"
},
"shareIndex": {
"format": "int32",
"type": "integer"
}
},
"type": "object"
},
"SubmitGuardianAttestationRequest": {
"additionalProperties": false,
"properties": {
"attestationSignature": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"SubmitShareByGuardianTokenRequest": {
"additionalProperties": false,
"properties": {
"guardianIdentity": {
"nullable": true,
"type": "string"
},
"recoveryAttemptId": {
"format": "uuid",
"type": "string"
},
"shareIndex": {
"format": "int32",
"type": "integer"
},
"submittedByContactId": {
"format": "uuid",
"type": "string"
},
"wrappedShare": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"SubmitShareRequest": {
"additionalProperties": false,
"properties": {
"recoveryAttemptId": {
"format": "uuid",
"type": "string"
},
"shareIndex": {
"format": "int32",
"type": "integer"
},
"submittedByContactId": {
"format": "uuid",
"type": "string"
},
"wrappedShare": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"SubmitShareResponse": {
"additionalProperties": false,
"properties": {
"canReconstruct": {
"type": "boolean"
},
"isValid": {
"type": "boolean"
},
"recoveryAttemptId": {
"format": "uuid",
"type": "string"
},
"shareIndex": {
"format": "int32",
"type": "integer"
},
"submittedAt": {
"format": "date-time",
"type": "string"
},
"submittedShareId": {
"format": "uuid",
"type": "string"
},
"thresholdRequired": {
"format": "int32",
"type": "integer"
},
"totalSharesSubmitted": {
"format": "int32",
"type": "integer"
},
"validationError": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"SubmittedShareDto": {
"additionalProperties": false,
"properties": {
"id": {
"format": "uuid",
"type": "string"
},
"isValid": {
"type": "boolean"
},
"recoveryAttemptId": {
"format": "uuid",
"type": "string"
},
"shareIndex": {
"format": "int32",
"type": "integer"
},
"submittedAt": {
"format": "date-time",
"type": "string"
},
"submittedByContactId": {
"format": "uuid",
"type": "string"
},
"validationError": {
"nullable": true,
"type": "string"
},
"wrappedShare": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"UpdateRecoveryConfigurationRequest": {
"additionalProperties": false,
"properties": {
"schemeType": {
"nullable": true,
"type": "string"
},
"threshold": {
"format": "int32",
"type": "integer"
},
"totalShares": {
"format": "int32",
"type": "integer"
}
},
"type": "object"
},
"VerifyShareRequest": {
"additionalProperties": false,
"properties": {
"recoveryConfigurationId": {
"format": "uuid",
"type": "string"
},
"shareChecksum": {
"nullable": true,
"type": "string"
},
"shareIndex": {
"format": "int32",
"type": "integer"
}
},
"type": "object"
}
},
"securitySchemes": {
"Bearer": {
"bearerFormat": "JWT",
"description": "JWT Authorization header using the Bearer scheme.",
"scheme": "bearer",
"type": "http"
}
}
},
"info": {
"contact": {
"email": "support@essence.local",
"name": "Essence Platform Team"
},
"description": "API for Shamir Secret Sharing key recovery workflows.\n\nAll endpoints require a Bearer token (SEC-001).",
"title": "Shamir Recovery Service API",
"version": "v1.0"
},
"openapi": "3.0.1",
"paths": {
"/api/v1/internal/recovery-enrolment/events/lookup": {
"post": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/RecoveryLifecycleEventLookupRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/RecoveryLifecycleEventLookupRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/RecoveryLifecycleEventLookupRequest"
}
}
},
"description": "The users asked about (at most 500) and the window."
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/RecoveryLifecycleEvent"
},
"type": "array"
}
}
},
"description": "The events, oldest first; empty when no named user had recovery activity in the window."
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "More than 500 users, an empty GUID, a missing bound, or the window end before its start."
},
"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 a service principal."
}
},
"summary": "The recovery-attempt lifecycle events of the named users in an inclusive window (#22121):\r\n`Initiated` at each initiation, `Completed` or `Failed` at each termination.",
"tags": [
"RecoveryEnrolmentPosture"
]
}
},
"/api/v1/internal/recovery-enrolment/guardian-links/lookup": {
"post": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/RecoveryGuardianLinkLookupRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/RecoveryGuardianLinkLookupRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/RecoveryGuardianLinkLookupRequest"
}
}
},
"description": "The members (at most 500) and the accounts that count as guardians (at most 500)."
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/RecoveryGuardianLink"
},
"type": "array"
}
}
},
"description": "The edges, ordered by guardian then member; empty when nobody depends on a named guardian."
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "More than 500 of either, or an empty GUID."
},
"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 a service principal."
}
},
"summary": "Which of the named members depend on which of the named guardians, one edge per (guardian,\r\nmember) whose share on the member's startable configuration can contribute (#22122).",
"tags": [
"RecoveryEnrolmentPosture"
]
}
},
"/api/v1/internal/recovery-enrolment/posture/lookup": {
"post": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/RecoveryEnrolmentPostureLookupRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/RecoveryEnrolmentPostureLookupRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/RecoveryEnrolmentPostureLookupRequest"
}
}
},
"description": "The users asked about (at most 500)."
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/RecoveryEnrolmentPosture"
},
"type": "array"
}
}
},
"description": "One row per distinct requested user; an unconfigured user is a row with zero guardians."
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "More than 500 users, or an empty GUID."
},
"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 a service principal."
}
},
"summary": "The recovery enrolment posture of each named user, one row per distinct user.",
"tags": [
"RecoveryEnrolmentPosture"
]
}
},
"/api/v1/internal/recovery-enrolment/self-service-link": {
"post": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/SelfServiceRecoveryLinkRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/SelfServiceRecoveryLinkRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/SelfServiceRecoveryLinkRequest"
}
}
},
"description": "The organisation and the member."
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SelfServiceRecoveryLinkResponse"
}
}
},
"description": "The link was committed for delivery to the member's channel of record."
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "An empty organisation or user reference."
},
"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 a service principal."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The member cannot self-serve (no startable configuration with a contributing guardian); nothing was sent."
},
"429": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The member has already been sent the maximum number of links in the window; nothing was sent."
}
},
"summary": "Sends the member a link that starts their own guardian recovery.",
"tags": [
"RecoveryEnrolmentSelfServiceLink"
]
}
},
"/api/v1/internal/recovery/custody/{userId}": {
"get": {
"parameters": [
{
"description": "The subject to answer about.",
"in": "path",
"name": "userId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RecoveryCustodyPostureResult"
}
}
},
"description": "The posture. `hasSurvivingConfiguration=false` is a real answer — EPIC 1 holds no\r\nstartable configuration for this subject — and is never a substitute for an error: a caller\r\nthat receives no response at all must treat the question as unanswered, not as \"false\"."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No valid bearer token."
}
},
"summary": "Whether the subject still holds startable recovery material.",
"tags": [
"InternalRecoveryCustody"
]
}
},
"/api/v1/recovery/attempts/dry-run": {
"get": {
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RecoveryDryRunResponse"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/RecoveryDryRunResponse"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/RecoveryDryRunResponse"
}
}
},
"description": "The dry run's current state."
},
"404": {
"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 has no dry run."
},
"429": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Too Many Requests"
}
},
"summary": "Reads the caller's current recovery dry run (#4718).",
"tags": [
"RecoveryWorkflow"
]
},
"post": {
"description": "Nothing is reconstructed and no share is collected. The rehearsal has no transport key, so\r\nthere is no path from here to key material — the impossibility is structural rather than\r\nchecked.",
"responses": {
"202": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RecoveryDryRunResponse"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/RecoveryDryRunResponse"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/RecoveryDryRunResponse"
}
}
},
"description": "Dry run started; guardians are being asked."
},
"404": {
"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 has no active recovery configuration."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "A dry run is already running, or no guardian has enrolled a key."
},
"429": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Dry-run rate limit exceeded."
}
},
"summary": "Extracts the authenticated user identifier from the JWT principal.\r\nReads the standard `NameIdentifier` / `sub` claims. Returns\r\nfalse when no authenticated user id is present or it is not a GUID, so\r\ncallers can short-circuit with 401 rather than trusting request input\r\n(A01 IDOR hardening, sf-2026-05-26-006 / sf-2026-05-26-009).",
"tags": [
"RecoveryWorkflow"
]
}
},
"/api/v1/recovery/attempts/dry-run/cancel": {
"post": {
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RecoveryDryRunResponse"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/RecoveryDryRunResponse"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/RecoveryDryRunResponse"
}
}
},
"description": "Dry run cancelled."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "There is no dry run to cancel."
},
"429": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Too Many Requests"
}
},
"summary": "Stops the caller's dry run early (#4718).",
"tags": [
"RecoveryWorkflow"
]
}
},
"/api/v1/recovery/attempts/{attemptId}": {
"get": {
"parameters": [
{
"description": "Recovery attempt identifier",
"in": "path",
"name": "attemptId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RecoveryInitiationQuorumResponse"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/RecoveryInitiationQuorumResponse"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/RecoveryInitiationQuorumResponse"
}
}
},
"description": "Recovery attempt retrieved successfully"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Recovery attempt not found"
}
},
"summary": "Gets a recovery attempt by its ID.",
"tags": [
"RecoveryWorkflow"
]
}
},
"/api/v1/recovery/attempts/{attemptId}/guardian-context": {
"get": {
"description": "\n\r\n This read does NOT consume the token. The submission it precedes needs the\r\n same single-use token, so spending it here would make the read fatal to the write\r\n it exists to enable. Replay is still reported (409) — the ledger is read, never\r\n written — and `POST submit-share/by-guardian-token` remains the sole atomic\r\n authority for single-use.\r\n \r\n\n\r\n Zero-knowledge. Display name only, never an email; no guardian roster, no\r\n other guardian's state. The recovering user's own screen anonymises their\r\n guardians (Decision D-254), and this must not disclose more to a third party than\r\n to the account holder.\r\n ",
"parameters": [
{
"description": "The recovery attempt the token is bound to.",
"in": "path",
"name": "attemptId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"description": "The per-share bearer token (header).",
"in": "header",
"name": "X-Guardian-Token",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GuardianRecoveryContextResponse"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/GuardianRecoveryContextResponse"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/GuardianRecoveryContextResponse"
}
}
},
"description": "Context returned; the token is untouched."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forged / malformed / expired token."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Wrong-scope token, or a token bound to a different recovery."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The recovery attempt is unknown or has ended."
},
"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 token has already been used to submit."
},
"429": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Too Many Requests"
}
},
"summary": "Serves a token-bearing guardian the request context they need in order to\r\nre-wrap their share under FR-01.062 (debt-2026-08-15-107): who is asking, when\r\nthey asked, which share this link is for, and the recovering device's transport\r\npublic key to wrap to.",
"tags": [
"RecoveryWorkflow"
]
}
},
"/api/v1/recovery/attest/{token}": {
"get": {
"description": "SEC-001/002 exception — see the controller remarks.",
"parameters": [
{
"in": "path",
"name": "token",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GuardianAttestationChallengeResponse"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/GuardianAttestationChallengeResponse"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/GuardianAttestationChallengeResponse"
}
}
},
"description": "Challenge resolved."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Token is unknown, already used, or expired."
},
"429": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Too Many Requests"
}
},
"summary": "Loads an attestation challenge by its single-use token (FR-01.083a). The\r\nattestation page (essence-web `/recovery/guardian/attest`) calls this on\r\nload; the server stamps the page-loaded observation, records the first load as\r\n`attestation-page-loaded` on the recovery audit chain, and returns the\r\nbound nonce + expiry.",
"tags": [
"GuardianAttestation"
]
},
"post": {
"description": "SEC-001/002 exception — see the controller remarks. Zero-knowledge: only the signature is submitted.",
"parameters": [
{
"in": "path",
"name": "token",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/SubmitGuardianAttestationRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/SubmitGuardianAttestationRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/SubmitGuardianAttestationRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GuardianAttestationResultResponse"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/GuardianAttestationResultResponse"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/GuardianAttestationResultResponse"
}
}
},
"description": "Submission processed (see `verified`)."
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Malformed signature."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Token is unknown, already used, or expired."
},
"429": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Too Many Requests"
}
},
"summary": "Submits a guardian attestation (FR-01.083 / FR-01.083a): the client-derived\r\nEd25519 signature over the challenge nonce. The server verifies it against\r\nthe share's enrolled public key.",
"tags": [
"GuardianAttestation"
]
}
},
"/api/v1/recovery/audit/verify": {
"get": {
"parameters": [
{
"description": "Optional recovery-session scope; verifies the full chain when null.",
"in": "query",
"name": "sessionId",
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RecoveryAuditChainVerificationResponse"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/RecoveryAuditChainVerificationResponse"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/RecoveryAuditChainVerificationResponse"
}
}
},
"description": "Verification completed (see `isValid`)."
}
},
"summary": "Verifies the tamper-evident social-recovery audit chain (FR-01.040). Re-computes\r\nevery entry's hash and confirms the forward-only chain is contiguous, so a\r\nstakeholder/auditor can detect any historical edit. An optional\r\nsessionId scopes the check to a single recovery session's\r\nsubchain; omit it to verify the whole chain from genesis.",
"tags": [
"RecoveryWorkflow"
]
}
},
"/api/v1/recovery/configuration": {
"get": {
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/RecoveryConfigurationResponse"
},
"type": "array"
}
},
"text/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/RecoveryConfigurationResponse"
},
"type": "array"
}
},
"text/plain": {
"schema": {
"items": {
"$ref": "#/components/schemas/RecoveryConfigurationResponse"
},
"type": "array"
}
}
},
"description": "Recovery configurations retrieved successfully"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid user identity"
}
},
"summary": "Lists all recovery configurations for the authenticated user.",
"tags": [
"RecoveryConfiguration"
]
},
"post": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/CreateRecoveryConfigurationRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateRecoveryConfigurationRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/CreateRecoveryConfigurationRequest"
}
}
},
"description": "Recovery configuration details"
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RecoveryConfigurationResponse"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/RecoveryConfigurationResponse"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/RecoveryConfigurationResponse"
}
}
},
"description": "Recovery configuration created successfully"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid request"
},
"401": {
"description": "No fresh `act=recovery-settings-change` elevation (`step-up-required`, DVS-4.4c)."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Recovery configuration already exists for user"
},
"423": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Locked"
}
},
"summary": "Creates a new recovery configuration for a user.",
"tags": [
"RecoveryConfiguration"
]
}
},
"/api/v1/recovery/configuration/guardians/{shareId}/replace": {
"post": {
"description": "Every share is reissued, which Shamir makes unavoidable — one secret is split, and old\r\npieces cannot be mixed with new ones. What this avoids is making the unchanged guardians\r\nsay yes again to a commitment they already made to the same person; they are told instead.\r\n \r\nThe live configuration keeps serving until the replacement's shares reach the threshold,\r\nso there is no window in which the account holder has no way back.",
"parameters": [
{
"description": "The share slot whose guardian is leaving.",
"in": "path",
"name": "shareId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/RecoveryContactNominationInput"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/RecoveryContactNominationInput"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/RecoveryContactNominationInput"
}
}
},
"description": "Who takes their place."
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RecoveryContactNominationResponse"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/RecoveryContactNominationResponse"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/RecoveryContactNominationResponse"
}
}
},
"description": "Replacement recorded; the new guardian has been invited and the rest told."
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The replacement is the same guardian, or the set breaks an FR-01.079 constraint."
},
"401": {
"description": "No fresh `act=recovery-settings-change` elevation (`step-up-required`, DVS-4.4c)."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No active configuration, or that share is not on it."
},
"423": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Locked"
}
},
"summary": "Replaces ONE guardian, keeping every other guardian's acceptance (#4718 item 3).",
"tags": [
"RecoveryConfiguration"
]
}
},
"/api/v1/recovery/configuration/nominations": {
"post": {
"description": "The scheme-only M:Essence.Core.ShamirRecovery.Api.Controllers.RecoveryConfigurationController.CreateRecoveryConfiguration(Essence.Core.ShamirRecovery.Contracts.Requests.CreateRecoveryConfigurationRequest,Essence.Core.ShamirRecovery.Application.Services.IRecoverySettingsStepUpGate,System.Threading.CancellationToken) endpoint records\r\nhow many shares exist but nothing about who holds them,\r\nand share generation requires a checksum and an account id per guardian —\r\nso before this endpoint a user's chosen contacts had nowhere to be\r\nrecorded. Zero-knowledge: only scheme parameters and contact metadata cross\r\nthe wire; shares are split and wrapped on the device.",
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/NominateRecoveryContactsRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/NominateRecoveryContactsRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/NominateRecoveryContactsRequest"
}
}
},
"description": "Scheme parameters and the chosen contacts."
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RecoveryContactNominationResponse"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/RecoveryContactNominationResponse"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/RecoveryContactNominationResponse"
}
}
},
"description": "Recovery contacts nominated and invitations dispatched."
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid scheme, or the guardian set violates an FR-01.079 constraint."
},
"401": {
"description": "No fresh `act=recovery-settings-change` elevation (`step-up-required`, DVS-4.4c)."
},
"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 caller's configuration already has a nominated guardian set."
},
"423": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Locked"
}
},
"summary": "Nominates the named people who will hold this user's recovery shares\r\n(FR-01.079), creating the recovery configuration when the caller does not\r\nyet have one, and dispatching each nominee's invitation (FR-01.070).",
"tags": [
"RecoveryConfiguration"
]
}
},
"/api/v1/recovery/configuration/redistributed": {
"post": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/RegisterRedistributedRecoveryConfigurationRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/RegisterRedistributedRecoveryConfigurationRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/RegisterRedistributedRecoveryConfigurationRequest"
}
}
},
"description": "New-generation scheme parameters."
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RecoveryConfigurationResponse"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/RecoveryConfigurationResponse"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/RecoveryConfigurationResponse"
}
}
},
"description": "Distributed configuration registered."
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid request or no user identity."
},
"401": {
"description": "No fresh `act=recovery-settings-change` elevation (`step-up-required`, DVS-4.4c)."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No Active configuration exists to redistribute from."
},
"423": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Locked"
}
},
"summary": "Registers a new-generation recovery configuration in the non-serving `Distributed`\r\nstate during post-rotation share redistribution (FR-01.068 / AC-01.061). The caller's\r\nexisting `Active` configuration keeps serving recovery sessions until the new shares\r\nreach the k-of-n threshold and are atomically promoted.",
"tags": [
"RecoveryConfiguration"
]
}
},
"/api/v1/recovery/configuration/redistributed/promote": {
"post": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/PromoteRedistributedRecoveryConfigurationRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/PromoteRedistributedRecoveryConfigurationRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/PromoteRedistributedRecoveryConfigurationRequest"
}
}
},
"description": "Target configuration id and established-share count."
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PromoteRedistributedRecoveryConfigurationResult"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/PromoteRedistributedRecoveryConfigurationResult"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/PromoteRedistributedRecoveryConfigurationResult"
}
}
},
"description": "Establishment recorded; swap performed or deferred."
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid request or no user identity."
},
"401": {
"description": "No fresh `act=recovery-settings-change` elevation (`step-up-required`, DVS-4.4c)."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Target configuration not found for the caller."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Target configuration is not in the Distributed state."
},
"423": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Locked"
}
},
"summary": "Records the client-verified established-share count for a `Distributed` configuration\r\nand, when the k-of-n threshold is reached, performs the FR-01.068 atomic swap (AC-01.061):\r\nthe new configuration is promoted to `Active` and the previously-active configuration\r\nis invalidated in a single transaction. If the threshold is not met, the old configuration\r\nis retained as the read-valid fallback and a recovery-degraded warning is emitted.",
"tags": [
"RecoveryConfiguration"
]
}
},
"/api/v1/recovery/configuration/resolve": {
"post": {
"description": "\n\r\n Always HTTP 200, and deliberately so. Someone who has lost every device\r\n holds no session and no user id, so this is necessarily an unauthenticated read\r\n against the platform's highest-risk surface — which means it must not become a\r\n membership oracle. Unknown account, known account with no recovery configuration,\r\n and configuration-not-startable all return the SAME body:\r\n `{ resolved: false, recoveryConfigurationId: null }`. A 404 for one of them\r\n would be exactly the signal being withheld.\r\n \r\n\n\r\n Rate-limited by IP (SEC-004) at the same cap as recovery initiation, since\r\n there is no principal to partition by; and the address is never a log field on\r\n any path.\r\n ",
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/ResolveRecoveryConfigurationRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/ResolveRecoveryConfigurationRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ResolveRecoveryConfigurationRequest"
}
}
},
"description": "The typed address."
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RecoveryConfigurationResolutionResponse"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/RecoveryConfigurationResolutionResponse"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/RecoveryConfigurationResolutionResponse"
}
}
},
"description": "Resolution completed — inspect `resolved`."
},
"429": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Too many resolution attempts from this address."
}
},
"summary": "Resolves the address a locked-out reader typed into the\r\n`recoveryConfigurationId` that `POST /api/v1/recovery/initiate`\r\nrequires (debt-2026-08-15-106, journey `account-recovery-lost-devices`).",
"tags": [
"RecoveryConfiguration"
]
}
},
"/api/v1/recovery/configuration/{configId}": {
"delete": {
"parameters": [
{
"description": "Recovery configuration identifier",
"in": "path",
"name": "configId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"204": {
"description": "Recovery configuration deactivated successfully"
},
"401": {
"description": "No fresh `act=recovery-settings-change` elevation (`step-up-required`, DVS-4.4c)."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Recovery configuration not found"
},
"423": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Locked"
}
},
"summary": "Deactivates a recovery configuration (soft delete per DAT-002).",
"tags": [
"RecoveryConfiguration"
]
},
"put": {
"parameters": [
{
"description": "Recovery configuration identifier",
"in": "path",
"name": "configId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/UpdateRecoveryConfigurationRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateRecoveryConfigurationRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/UpdateRecoveryConfigurationRequest"
}
}
},
"description": "Updated configuration details"
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RecoveryConfigurationResponse"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/RecoveryConfigurationResponse"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/RecoveryConfigurationResponse"
}
}
},
"description": "Recovery configuration updated successfully"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid scheme parameters"
},
"401": {
"description": "No fresh `act=recovery-settings-change` elevation (`step-up-required`, DVS-4.4c)."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Recovery configuration not found"
},
"423": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Locked"
}
},
"summary": "Updates an existing recovery configuration's threshold scheme.",
"tags": [
"RecoveryConfiguration"
]
}
},
"/api/v1/recovery/configuration/{configId}/guardians/invitation": {
"post": {
"parameters": [
{
"description": "Recovery configuration the nomination belongs to (token-bound).",
"in": "path",
"name": "configId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"description": "The invitation-acceptance bearer token (header).",
"in": "header",
"name": "X-Guardian-Token",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/RespondToGuardianInvitationRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/RespondToGuardianInvitationRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/RespondToGuardianInvitationRequest"
}
}
},
"description": "Accept/decline decision + the guardian's canonical identity."
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RespondToGuardianInvitationResponse"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/RespondToGuardianInvitationResponse"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/RespondToGuardianInvitationResponse"
}
}
},
"description": "Decision recorded; token consumed."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forged / malformed / expired token."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Wrong-scope token (e.g. a share-submission token), or an identity/configuration binding mismatch."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Configuration not found, or no share is nominated to this guardian."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Token already consumed (replay)."
},
"429": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Too Many Requests"
}
},
"summary": "Records a guardian's FR-01.070 invitation accept/decline decision,\r\nauthenticated by an FR-01.007a guardian invitation-acceptance bearer\r\ntoken (debt-2026-06-21-1423) — the path an email-only guardian (no\r\nEssence account session) uses. The token is carried in the\r\n`X-Guardian-Token` header and is HMAC-bound to\r\n`{guardianIdentity, configurationId, nominatedShareIndices}`.",
"tags": [
"RecoveryWorkflow"
]
}
},
"/api/v1/recovery/configuration/{userId}": {
"get": {
"parameters": [
{
"description": "Route value retained for backward-compatible URLs (and the\r\nM:Essence.Core.ShamirRecovery.Api.Controllers.RecoveryConfigurationController.CreateRecoveryConfiguration(Essence.Core.ShamirRecovery.Contracts.Requests.CreateRecoveryConfigurationRequest,Essence.Core.ShamirRecovery.Application.Services.IRecoverySettingsStepUpGate,System.Threading.CancellationToken) Location header). It is ignored:\r\nthe configuration returned is always the caller's own, resolved from the\r\nJWT principal.",
"in": "path",
"name": "userId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RecoveryConfigurationResponse"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/RecoveryConfigurationResponse"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/RecoveryConfigurationResponse"
}
}
},
"description": "Recovery configuration retrieved successfully"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Recovery configuration not found"
}
},
"summary": "Gets the authenticated caller's recovery configuration.",
"tags": [
"RecoveryConfiguration"
]
}
},
"/api/v1/recovery/guardians/invitation-context": {
"get": {
"description": "\n\r\n This read does NOT consume the token. The accept/decline it precedes needs the same\r\n single-use token, so spending it to render the page would make answering impossible.\r\n Replay is still reported (409) — the ledger is read, never written — and\r\n `POST configuration/{configId}/guardians/invitation` remains the sole atomic\r\n authority for single-use. Exactly the split the share-submission pair already makes.\r\n \r\n\n\r\n The route takes no ids. Everything is derived from the token's MAC-trusted claims:\r\n a reader holding only an emailed link asserts no identity and must not be able to name a\r\n configuration of their own. That also keeps the emailed URL to a single `?token=`\r\n parameter, which is what the notification can actually construct.\r\n \r\n\n\r\n Zero-knowledge. The arrangement, never the vault: no document count, no field name,\r\n nothing derived from contents, and a COUNT of the other holders rather than a roster —\r\n board 4b's promise that a guardian never learns \"who the other guardians are\".\r\n ",
"parameters": [
{
"description": "The invitation-acceptance bearer token (header).",
"in": "header",
"name": "X-Guardian-Token",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GuardianInvitationContextResponse"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/GuardianInvitationContextResponse"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/GuardianInvitationContextResponse"
}
}
},
"description": "Context returned; the token is untouched."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forged / malformed / expired token."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Wrong-scope token (e.g. a share-submission token)."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Configuration unknown, no nomination for this identity, or the share was invalidated."
},
"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 invitation has already been answered."
},
"429": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Too Many Requests"
}
},
"summary": "Reads what design board 4d must show a nominated guardian before they answer — who the\r\nscheme belongs to, what they would hold, and how many others hold a share — authenticated\r\nby the FR-01.007a invitation-acceptance token WITHOUT consuming it (#5723).",
"tags": [
"RecoveryWorkflow"
]
}
},
"/api/v1/recovery/guardians/recovery-context": {
"get": {
"description": "\n\r\n The emailed link was `/recovery/guardian/submit?token=` while the page required four\r\n further parameters no producer could supply, so every real approval email dead-ended.\r\n The route takes no ids for the reason\r\n M:Essence.Core.ShamirRecovery.Api.Controllers.RecoveryWorkflowController.GetGuardianInvitationContext(System.String,System.Threading.CancellationToken) takes none: a reader holding only a link\r\n asserts no identity and must not be able to name a recovery of their own.\r\n \r\n\n\r\n This read does NOT consume the token; replay is reported (409), never caused.",
"parameters": [
{
"description": "The per-share bearer token (header).",
"in": "header",
"name": "X-Guardian-Token",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GuardianRecoveryContextResponse"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/GuardianRecoveryContextResponse"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/GuardianRecoveryContextResponse"
}
}
},
"description": "Context returned; the token is untouched."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forged / malformed / expired token."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "A genuine token of the wrong scope."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The recovery attempt is unknown or has ended."
},
"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 token has already been used to submit."
},
"429": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Too Many Requests"
}
},
"summary": "The same guardian request context, for a guardian holding ONLY the token — which is all\r\nthe approval email (board 7g) can carry (#12292). The recovery attempt, the guardian\r\nidentity and the share index all come from the token's MAC-trusted claims, and the\r\nresponse hands back the attempt id, identity and provenance id the submission needs.",
"tags": [
"RecoveryWorkflow"
]
}
},
"/api/v1/recovery/initiate": {
"post": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/InitiateRecoveryRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/InitiateRecoveryRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/InitiateRecoveryRequest"
}
}
},
"description": "Recovery initiation details"
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RecoveryInitiationQuorumResponse"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/RecoveryInitiationQuorumResponse"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/RecoveryInitiationQuorumResponse"
}
}
},
"description": "FR-01.103: `withdrawGuardianQuorumId` — the request is withdrawn; nothing initiated"
},
"201": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RecoveryAttemptResponse"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/RecoveryAttemptResponse"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/RecoveryAttemptResponse"
}
}
},
"description": "Recovery attempt initiated successfully"
},
"202": {
"description": "FR-01.103: `requestGuardianQuorum` — the guardians have been asked to confirm; nothing initiated yet"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid 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": "FR-01.045 step-up elevation absent or unverifiable"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Recovery configuration 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": "An attempt is already in progress (FR-01.064) or a key rotation is active (FR-01.067)"
},
"429": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Too Many Requests"
}
},
"summary": "Initiates a key recovery attempt.",
"tags": [
"RecoveryWorkflow"
]
}
},
"/api/v1/recovery/initiation-quorums/{quorumId}": {
"get": {
"operationId": "GetRecoveryInitiationQuorum",
"parameters": [
{
"description": "FR-01.103 initiation-quorum id, on the `initiation-quorums/{quorumId}` route only.",
"in": "path",
"name": "quorumId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RecoveryInitiationQuorumResponse"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/RecoveryInitiationQuorumResponse"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/RecoveryInitiationQuorumResponse"
}
}
},
"description": "Recovery attempt retrieved successfully"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Recovery attempt not found"
}
},
"summary": "Gets a recovery attempt by its ID.",
"tags": [
"RecoveryWorkflow"
]
}
},
"/api/v1/recovery/reconstruct": {
"post": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/ReconstructSecretRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/ReconstructSecretRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ReconstructSecretRequest"
}
}
},
"description": "Reconstruction request"
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ReconstructSecretResponse"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ReconstructSecretResponse"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ReconstructSecretResponse"
}
}
},
"description": "Shares relayed, or the reconstruction confirmed"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Insufficient shares"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Recovery attempt 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": "The attempt already ended, or a confirm of shares never relayed"
},
"429": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Too Many Requests"
}
},
"summary": "Reconstructs the secret from submitted shares.\r\nCRITICAL: Returns shares to the client for client-side reconstruction.\r\nTwo phases since #17586: a relay (the default) returns the shares and KEEPS them; a\r\nconfirm (`\"confirm\": true`) completes the attempt and erases them.",
"tags": [
"RecoveryWorkflow"
]
}
},
"/api/v1/recovery/rehearse": {
"post": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/RehearseReconstructionRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/RehearseReconstructionRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/RehearseReconstructionRequest"
}
}
},
"description": "Rehearsal request"
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RehearseReconstructionResponse"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/RehearseReconstructionResponse"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/RehearseReconstructionResponse"
}
}
},
"description": "Rehearsal completed; verdict returned"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid request"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Recovery attempt not found"
},
"429": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Too Many Requests"
}
},
"summary": "Rehearses (dry-runs) a reconstruction without reconstructing the secret.\r\nCRITICAL: returns only a readiness verdict — no share material, no UMK\r\nunwrap, no data release. This is the EPIC 18 → EPIC 1\r\npre-mortem seam (journey executor-plan-pre-mortem-rehearsal-dry-run,\r\ndebt-2026-06-18-295). The rehearsal emits an auditable\r\nRecoveryRehearsalCompletedIntegrationEvent (run-type=rehearsal) asserting\r\nthe zero-knowledge boundary held.",
"tags": [
"RecoveryWorkflow"
]
}
},
"/api/v1/recovery/shares/generate": {
"post": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/GenerateSharesRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenerateSharesRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/GenerateSharesRequest"
}
}
},
"description": "Share metadata details"
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenerateSharesResponse"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/GenerateSharesResponse"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/GenerateSharesResponse"
}
}
},
"description": "Share metadata generated successfully"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid request"
},
"401": {
"description": "No fresh `act=recovery-settings-change` elevation (`step-up-required`, DVS-4.4c)."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Recovery configuration not found"
},
"423": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Locked"
}
},
"summary": "Generates share metadata for distribution.",
"tags": [
"ShareManagement"
]
}
},
"/api/v1/recovery/shares/verify": {
"post": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/VerifyShareRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/VerifyShareRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/VerifyShareRequest"
}
}
},
"description": "Share verification details"
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ShareVerificationResponse"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ShareVerificationResponse"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ShareVerificationResponse"
}
}
},
"description": "Share verification completed"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid request"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Recovery configuration not found"
}
},
"summary": "Verifies share integrity by comparing its checksum against stored metadata.\r\nThis is a zero-knowledge verification — the server only sees checksums,\r\nnever actual share data.",
"tags": [
"ShareManagement"
]
}
},
"/api/v1/recovery/shares/{recoveryId}/status": {
"get": {
"parameters": [
{
"description": "Recovery attempt identifier",
"in": "path",
"name": "recoveryId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ShareCollectionStatusResponse"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ShareCollectionStatusResponse"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ShareCollectionStatusResponse"
}
}
},
"description": "Status retrieved successfully"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Recovery attempt not found"
}
},
"summary": "Gets the share collection status for a recovery attempt.",
"tags": [
"ShareManagement"
]
}
},
"/api/v1/recovery/shares/{shareId}/attestation/challenge": {
"post": {
"parameters": [
{
"in": "path",
"name": "shareId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GuardianAttestationChallengeResponse"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/GuardianAttestationChallengeResponse"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/GuardianAttestationChallengeResponse"
}
}
},
"description": "Challenge issued."
},
"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": "Share 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": "Share has no enrolled attestation key."
}
},
"summary": "Issues a fresh attestation challenge for an enrolled share (FR-01.083).\r\nAuthenticated path for an in-app (account-holder) guardian who requests an\r\non-demand attestation.",
"tags": [
"GuardianAttestation"
]
}
},
"/api/v1/recovery/shares/{shareId}/attestation/enrol": {
"post": {
"parameters": [
{
"in": "path",
"name": "shareId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/EnrolGuardianAttestationKeyRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/EnrolGuardianAttestationKeyRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/EnrolGuardianAttestationKeyRequest"
}
}
}
},
"responses": {
"204": {
"description": "Attestation key enrolled."
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Malformed public key or cadence out of range."
},
"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": "Share not found."
}
},
"summary": "Enrols (or re-enrols) the guardian's Ed25519 attestation public key for a\r\nshare (FR-01.083). Authenticated — the owning user / account-holder\r\nguardian registers the public key derived client-side from the share.",
"tags": [
"GuardianAttestation"
]
}
},
"/api/v1/recovery/submit-share": {
"post": {
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/SubmitShareRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/SubmitShareRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/SubmitShareRequest"
}
}
},
"description": "Share submission details"
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SubmitShareResponse"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/SubmitShareResponse"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/SubmitShareResponse"
}
}
},
"description": "Share submitted successfully"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid share"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Recovery attempt not found"
},
"429": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Too Many Requests"
}
},
"summary": "Submits a share during a recovery attempt.",
"tags": [
"RecoveryWorkflow"
]
}
},
"/api/v1/recovery/submit-share/by-guardian-token": {
"post": {
"parameters": [
{
"description": "The per-share bearer token (header).",
"in": "header",
"name": "X-Guardian-Token",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/SubmitShareByGuardianTokenRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/SubmitShareByGuardianTokenRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/SubmitShareByGuardianTokenRequest"
}
}
},
"description": "Token-authenticated share submission details."
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SubmitShareResponse"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/SubmitShareResponse"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/SubmitShareResponse"
}
}
},
"description": "Share submitted; token consumed."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forged / malformed / expired token."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Wrong-scope token, or a cross-share / identity binding mismatch."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Recovery attempt 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": "Token already consumed (replay)."
},
"429": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Too Many Requests"
}
},
"summary": "Submits a wrapped recovery share authenticated by an FR-01.007a guardian\r\nper-share bearer token (debt-2026-06-21-1423) — the path an\r\nemail-only guardian (no Essence account session) uses. The token is\r\ncarried in the `X-Guardian-Token` header and is HMAC-bound to\r\n`{recoverySessionId, shareIndex, guardianIdentity}`.",
"tags": [
"RecoveryWorkflow"
]
}
}
},
"security": [
{
"Bearer": []
}
],
"tags": [
{
"description": "Guardian share-health attestation surface (FR-01.083 / FR-01.083a,\r\ndebt-2026-05-29-019/-047/-125/-011). Periodic proof that a guardian can still\r\nunwrap their recovery share — surfacing a silently-lost OOB passphrase before\r\na real recovery is attempted.",
"name": "GuardianAttestation"
},
{
"description": "EPIC 1 producer surface answering, for a named subject, whether any recovery material still\r\nsurvives (journey `ex-offender-resettlement-identity-and-records-reestablishment`,\r\ndebt-2026-08-20-091).",
"name": "InternalRecoveryCustody"
},
{
"description": "Controller for managing recovery configurations.",
"name": "RecoveryConfiguration"
},
{
"description": "EPIC 1 producer of the metadata-only recovery-enrolment posture the EPIC 7 org account-recovery\r\nsurface aggregates (#12196, FR-07.022 / FR-07.025), and of the guardian links behind its\r\ndeparting-guardian picker and bulk re-nominate (#22122, FR-07.023), and of the recovery-attempt\r\nlifecycle events behind its compliance export (#22121, FR-07.024).",
"name": "RecoveryEnrolmentPosture"
},
{
"description": "EPIC 1 producer of the helpdesk's self-service recovery link (FR-07.026, #22123): the EPIC 7\r\nhelpdesk asks, EPIC 1 decides whether the member can self-serve and enqueues the link to the\r\nmember's channel of record.",
"name": "RecoveryEnrolmentSelfServiceLink"
},
{
"description": "Controller for managing the recovery workflow.",
"name": "RecoveryWorkflow"
},
{
"description": "Controller for managing share metadata and distribution.",
"name": "ShareManagement"
}
]
}