Create Recovery Challenge
POST /auth/recover/user/init
Starts a user recovery session, returning a challenge that will be used to verify the user's identity.
Request headers required. See Request Headers for more information.
Required Permissions
Since this endpoint is not authenticated, the permissions apply to the application only.
Name
Conditions
Auth:Users:Read
Always Required
Request body
username *
String
Email address of the user
verificationCode *
String
The secret value that the user received in their recovery email
orgId *
String
ID of the target Org
credentialId *
String
The crdential ID of the user's recovery credential
Example
{
"username": "jdoe@example.co",
"verificationCode": "1234-1234-1234-1234",
"orgId": "or-34513-nip9c-8bppvgqgj28dbodrc",
"credentialId": "GMkW0zlmcoMxI1OX0Z96LL_Mz7dgeu6vOH5_TOeGyNk"
}Responses
See Common Errors for common errors.
See User Recovery Errors for user recovery specific errors.
Success - an object containing the user's authentication options
Format:
{
// Relying Party information that identifies the application to the user
"rp": {
// the domain of the server that is requesting the credential. This must match the effective domain of the application communicating with the user's WebAuthn client
"id": "string",
// a user friendly name to help identify the server requesting the credential
"name": "string",
},
// identifies the user that is being logged into the Dfns API
"user": {
// id that ties the user to the credential created in the user's WebAuthn client
"id": "string",
// additional value that will be displayed to the user on the WebAuthn client's display
"name": "string",
// name that will be displayed to the user on the WebAuthn client's display
"displayName": "string"
},
// temporary authentication token that is used to identify the recovery session with the matching call to Recover User
"temporaryAuthenticationToken": "string",
// list of the kinds of credentials that the user can use when recovering
"supportedCredentialKinds": {
// list of the credential kinds that are supported as a first factor credential
"firstFactor": ["string"],
// list of the credential kinds that are supported as a second factor credential
"secondFactor": ["string"]
},
// random value used to uniquely identify the request. This value will be included in the data that is signed
"challenge": "string",
// list of objects that identify the signing algorithms that are supported
"pubKeyCredParam": [
{
// will always be `public-key`
"type": "public-key",
// an integer that identifies a signing algorithm. Can be either `-7` for ES256 or `-257` for RS256
"alg": "number"
},
],
// identifies the information needed to verify the user's signing certificate; can be one of the following:
// * none: indicates no attestation data is required
// * indirect: indicates the attestation data should be given, but that it can be generated using an Anonymization CA
// * direct: indicates the attestation data must be given and should be generated by the authenticator
// * enterprise: indicates the attestation data should include information to uniquely identify the user's device
"attestation": "string",
// a list of objects that identify credentials that the user's WebAuthn client should not use
"excludeCredentials": [
{
// will always be `public-key`
"type": "public-key",
// ID that can identify the credential on the authenticator
"id": "string",
// types of transports that are not allowed. Can be one of the following:
// * usb for usb support
// * nfc for near field communication (NFC) support
// * ble for bluetooth support
// * internal for non-removable authenticators
// * hybrid for multiple transport methods
"transports": "string"
}
],
// identifies the criteria that the user's WebAuthn client should use when creating the credential
"authenticatorSelection": {
// optional value indicating the type of authenticators that are supported. If not set then the authenticator type is not restricted. Can be one of the following:
// * platform for requiring the authenticator be tied to the users device (like a TPM)
// * cross-platform for the authenticator to be an external device (like a Yubikey)
"authenticatorAttachment": "string",
// value indicating whether or not the authenticator should use resident keys. Can be one of the following:
// * discouraged to indicate the authenticator should not use a resident key unless its the only option
// * preferred to indicate the authenticator should try to use a resident key if supported
// * required to indicate the authenticator must use a resident key
"residentKey": "required",
// value indicating if the authenticator needs to support resident keys
"requireResidentKey": "boolean",
// value indicating if the user should be prompted for a second factor. Can be one of the following values:
// * required to indicate the user must be prompted for their pin, biometrics, or another second factor option
// * preferred to indicate the user should be prompted for a second factor if it is supported
// * discouraged to indicate the user should not be prompted for their second factor unless the device requires it
"userVerification": "required"
},
// the list of recovery credentials that can be used to recover the user
"allowedRecoveryCredentials":[
{
// the credential ID of the recovery credential
"id": "string",
// the encrypted private key set when registering the recovery credential
"encryptedRecoveryKey": "string"
}
]
}Example
{
"rp": {
"id": "dfns.io",
"name": "Dfns",
},
"user": {
"id": "us-2ba0h-lvp2q-8v1860pcj1bh5irf",
"name": "jane@example.co",
"displayName": "jane@example.co"
},
"temporaryAuthenticationToken": "eyJ0eXAiOiJKV1Q...X1bwCg35kbzsjA",
"supportedCredentialKinds": {
"firstFactor": ["Fido2","Key"],
"secondFactor": ["Fido2","Key"]
},
"challenge": "MmE5YzRmMzMwY2NlNGUyMjhjZWYzMzlhZDBhZmIxNzk",
"pubKeyCredParam": [
{
"type": "public-key",
"alg": -7
},
{
"type": "public-key",
"alg": -257
}
],
"attestation": "direct",
"excludeCredentials": [],
"authenticatorSelection": {
"residentKey": "required",
"requireResidentKey": true,
"userVerification": "required"
},
"allowedRecoveryCredentials": [
{
"id": "GMkW0zlmcoMxI1OX0Z96LL_Mz7dgeu6vOH5_TOeGyNk",
"encryptedRecoveryKey": "LsXVskHYqqrKKxBC9KvqStLEmxak5Y7NaboDDlRSIW7evUJpQTT1AYvx0EsFskmriaVb3AjTCGEv7gqUKokml1USL7+dVmrUVhV+cNWtS5AorvRuZr1FMGVKFkW1pKJhFNH2e2O661UhpyXsRXzcmksA7ZN/V37ZK7ITue0gs6I="
}
]
}Last updated