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.
Required Permissions
None
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": "[email protected]",
"verificationCode": "1234-1234-1234-1234",
"orgId": "or-34513-nip9c-8bppvgqgj28dbodrc",
"credentialId": "GMkW0zlmcoMxI1OX0Z96LL_Mz7dgeu6vOH5_TOeGyNk"
}Responses
Success - an object containing the user's authentication options
Format:
{
// 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": "[email protected]",
"displayName": "[email protected]"
},
"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