# Create Delegated Recovery Challenge

`POST /auth/recover/user/delegated`

{% hint style="warning" %}
Only a [Service Account](../service-account-management) can use this endpoint.
{% endhint %}

This endpoint enables setting up a recovery workflow for Delegated Signing. Via this configuration, the end user will not receive an email from Dfns but instead can establish recovery credentials that leverage the customer's brand for the recovery workflow.

Once the user has been verified by your auth system and this API has been called, you can call [Recover User](createuserrecovery) to complete the recovery process.

{% hint style="info" %}
* Service account required. See [Service Accounts](../service-account-management) for more information.
* User action signature required. See [User Action Signing](../user-action-signing) for more information.
* Request headers required. See [Request Headers](../../../advanced-topics/authentication/request-headers) for more information.
* Authentication required. See [Authentication Headers](../../../../advanced-topics/authentication/request-headers#authentication-headers) for more information.
{% endhint %}

## Required Permissions

| Name                     | Conditions      |
| ------------------------ | --------------- |
| `Auth:Recover:Delegated` | Always Required |

## Request body

|                                                   |          |                                                    |
| ------------------------------------------------- | -------- | -------------------------------------------------- |
| `username` <mark style="color:red;">\*</mark>     | `String` | Email address of the user                          |
| `credentialId` <mark style="color:red;">\*</mark> | `String` | The crdential ID of the user's recovery credential |

### Example

```json
{
  "username": "jdoe@example.co",
  "credentialId": "GMkW0zlmcoMxI1OX0Z96LL_Mz7dgeu6vOH5_TOeGyNk"
}
```

## Responses

{% hint style="info" %}
* See [Common Errors](https://github.com/dfns/dfns-api-docs/blob/m/getting-started/errors.md#common-errors) for common errors.
* See [Delegated Authentication Errors](https://github.com/dfns/dfns-api-docs/blob/m/getting-started/errors.md#delegated-authentication-errors) for delegated authentication specific errors.
{% endhint %}

{% tabs %}
{% tab title="200" %}
**Success** - an object containing the user's authentication options

Format:

```json
{
  // 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 registering
  "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"
    }
  ]
}
```
{% endtab %}
{% endtabs %}

### Example

```json
{
  "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="
    }
  ]
}
```
