# Create Credential Challenge

`POST /auth/credentials/init`

Part of the flow [Create Credential Regular flow](https://docs-legacy.dfns.co/d/advanced-topics/authentication/credentials#regular-flow).

Starts a create user credential session, returning a challenge that will be used to verify the user's identity.

{% hint style="info" %}

* Request headers required. See [Request Headers](https://docs-legacy.dfns.co/d/advanced-topics/authentication/request-headers) for more information.
* Authentication required. See [Authentication Headers](https://docs-legacy.dfns.co/d/advanced-topics/authentication/request-headers#authentication-headers) for more information.
  {% endhint %}

## Required Permissions

None

## Request body

<table><thead><tr><th width="127.33333333333331"></th><th width="124"></th><th></th></tr></thead><tbody><tr><td><code>kind</code> <mark style="color:red;">*</mark></td><td><code>String</code></td><td>The kind of credential being added to the user's account; can be <code>Fido2</code>, <code>Key</code>, <code>PasswordProtectedKey</code> or <code>RecoveryKey</code> (see <a href="../..#credential-kinds">Credential Kind</a>)</td></tr></tbody></table>

```json
{
  "kind": "Fido2"
}
```

## 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 [Credential Management Errors](https://github.com/dfns/dfns-api-docs/blob/m/getting-started/errors.md#credential-management-errors) for credential management specific errors.
  {% endhint %}

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

Format:

```json
{
  // the kind of credential being created
  "kind": "string",
  // Challenge Identifier
  "challengeIdentifier": "string",
  // random value used to uniquely identify the request. This value will be included in the data that is signed
  "challenge": "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"
  },
  // 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"
  }
}
```

{% endtab %}
{% endtabs %}

### Example

```json
{
  "kind": "Fido2",
  "challengeIdentifier": "eyJ0eXAiOiJKV1Q...X1bwCg35kbzsjA",
  "challenge": "MmE5YzRmMzMwY2NlNGUyMjhjZWYzMzlhZDBhZmIxNzk",
  "rp": {
    "id": "dfns.io",
    "name": "Dfns",
  },
  "user": {
    "id": "us-2ba0h-lvp2q-8v1860pcj1bh5irf",
    "name": "jane@example.co",
    "displayName": "jane@example.co"
  },
  "pubKeyCredParam": [
    {
      "type": "public-key",
      "alg": -7
    },
    {
      "type": "public-key",
      "alg": -257
    }
  ],
  "attestation": "direct",
  "excludeCredentials": [],
  "authenticatorSelection": "",{
    "residentKey": "required",
    "requireResidentKey": true,
    "userVerification": "required"
  }
}
```