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": "[e-mail]",
  "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.

200

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": "[e-mail]",
    "displayName": "[e-mail]"
  },
  "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="
    }
  ]
}