# Create Credential

`POST /auth/credentials`

Part of the flow [Create Credential Regular flow](/d/advanced-topics/authentication/credentials.md#regular-flow).

Adds a new credential to a user's account. See [Credential Kinds](/d/advanced-topics/authentication/credentials.md#credential-kinds) for all supported credential types.

{% hint style="info" %}

* User action signature required. See [User Action Signing](/d/api-docs/authentication/user-action-signing.md) for more information.
* Request headers required. See [Request Headers](/d/advanced-topics/authentication/request-headers.md) for more information.
* Authentication required. See [Authentication Headers](/d/advanced-topics/authentication/request-headers.md#authentication-headers) for more information.
  {% endhint %}

## Required Permissions

None

## Request body

<table><thead><tr><th width="254">Field</th><th width="110.33333333333331">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>challengeIdentifier</code> <mark style="color:red;">*</mark></td><td><code>String</code></td><td>Challenge identifier returned by the <a href="/pages/qhWL3wft13z6sNR31Dzp">Create User Credential Challenge</a> call</td></tr><tr><td><code>credentialName</code> <mark style="color:red;">*</mark></td><td><code>String</code></td><td>Name the user is assigning to this credential</td></tr><tr><td><code>credentialKind</code> <mark style="color:red;">*</mark></td><td><code>String</code></td><td>Kind of credential being registered (see <a href="/pages/4fhQFGtqUCvaTBpttMYF#credential-kinds">Credential Kind</a>)</td></tr><tr><td><code>credentialInfo</code> <mark style="color:red;">*</mark></td><td><code>Object</code></td><td>An object containing information about the credential being registered</td></tr><tr><td><code>encryptedPrivateKey</code></td><td><code>String</code></td><td>Only for Password Protected Key and Recovery Key</td></tr></tbody></table>

### Fido2 Credential

<table><thead><tr><th></th><th width="109.33333333333331"></th><th></th></tr></thead><tbody><tr><td><code>credentialKind</code> <mark style="color:red;">*</mark></td><td><code>String</code></td><td>will always be <code>Fido2</code></td></tr><tr><td><code>credentialInfo</code> <mark style="color:red;">*</mark></td><td><code>Object</code></td><td>See fields below</td></tr><tr><td><code>credentialInfo.credId</code> <mark style="color:red;">*</mark></td><td><code>String</code></td><td>base64url encoded id of the credential</td></tr><tr><td><code>credentialInfo.clientData</code> <mark style="color:red;">*</mark></td><td><code>String</code></td><td>base64url encoded client data object. The underlying object is the clientData object returned by the user's WebAuthn client</td></tr><tr><td><code>credentialInfo.attestationData</code> <mark style="color:red;">*</mark></td><td><code>String</code></td><td>base64url encoded attestation data object. The underlying object is the attestationData object returned by the user's WebAuthn client</td></tr></tbody></table>

#### Example

```json
{
  "challengeIdentifier":"eyJ0e...fQNA",
  "credentialName": "My Credential",
  "credentialKind":"Fido2",
  "credentialInfo":{
    "credId":"c1QEdgnPLJargwzy3cbYKny4Q18u0hr97unXsF3DiE8",
    "clientData":"eyJ0eXBlIjoid2ViYXV0aG4uY3JlYXRlIiwiY2hhbGxlbmdlIjoiTVdNME1tWTVZVFEwTURSaU56ZGhOVEZoTnpZNU9EUXdOV0k1WlRRNFkyUmhPRFppTkRrM1pUWXpPVEU1T0dZeU1EY3haakJqWXprNE1tUTVZelkxTUEiLCJvcmlnaW4iOiJodHRwczovL2FwcC5kZm5zLm5pbmphIiwiY3Jvc3NPcmlnaW4iOmZhbHNlfQ",
    "attestationData":"WT-zFZUBbJHfBkmhzTlPf49LTn7asLeTQKhm_riCvFgFAAAAAA"
  }
}
```

### Key Credential

<table><thead><tr><th></th><th width="120.33333333333331"></th><th></th></tr></thead><tbody><tr><td><code>credentialKind</code> <mark style="color:red;">*</mark></td><td><code>String</code></td><td>will always be <code>Key</code></td></tr><tr><td><code>credentialInfo</code> <mark style="color:red;">*</mark></td><td><code>Object</code></td><td>See fields below</td></tr><tr><td><code>credentialInfo.credId</code> <mark style="color:red;">*</mark></td><td><code>String</code></td><td>base64url encoded id of the credential. Note: This can be any unique value that identifies the credential (eg. account+key ID on AWS, the key's database ID, or the path to the key on disk)</td></tr><tr><td><code>credentialInfo.clientData</code> <mark style="color:red;">*</mark></td><td><code>String</code></td><td>base64url encoded <a href="/pages/JxGDccxJ5ryH9AWX6OAe#key-password-protected-key-and-recovery-credential">Client Data</a> JSON string object that was signed with the user's private key</td></tr><tr><td><code>credentialInfo.attestationData</code> <mark style="color:red;">*</mark></td><td><code>String</code></td><td>base64url encoded <a href="/pages/JxGDccxJ5ryH9AWX6OAe#key-password-protected-key-and-recovery-credential-1">Attestation Data</a> JSON string object with the users signature and public key</td></tr></tbody></table>

#### Example

```json
{
  "challengeIdentifier":"eyJ0e...fQNA",
  "credentialName": "My Credential",
  "credentialKind":"Key",
  "credentialInfo":{
    "credId":"6Ca6tAOFTx2odyJBnCoRO-gPvfpfy0EOoOcEaxfxIOk",
    "clientData":"eyJ0eXBlIjoia2V5LmNyZWF0ZSIsImNoYWxsZW5nZSI6Ik1XTTBNbVk1WVRRME1EUmlOemRoTlRGaE56WTVPRFF3TldJNVpUUTRZMlJoT0RaaU5EazNaVFl6T1RFNU9HWXlNRGN4WmpCall6azRNbVE1WXpZMU1BIiwib3JpZ2luIjoiaHR0cHM6Ly9hcHAuZGZucy5uaW5qYSIsImNyb3NzT3JpZ2luIjpmYWxzZX0",
    "attestationData":"eyJjaGFsbGVuZ2UiOiJZMmd0Tm1Oc2RHTXRiV05sWTNZdE9XRTRPV2QxYnpKd1lqYzBOVEp4Y2ciLCJjcm9zc09yaWdpbiI6ZmFsc2UsIm9yaWdpbiI6Imh0dHBzOi8vYXBwLmRmbnMud3RmIiwidHlwZSI6ImtleS5jcmVhdGUifQ"
  }
}
```

### Password Protected Key Credential

<table><thead><tr><th></th><th width="120.33333333333331"></th><th></th></tr></thead><tbody><tr><td><code>credentialKind</code> <mark style="color:red;">*</mark></td><td><code>String</code></td><td>will always be <code>PasswordProtectedKey</code></td></tr><tr><td><code>credentialInfo</code> <mark style="color:red;">*</mark></td><td><code>Object</code></td><td>See fields below</td></tr><tr><td><code>credentialInfo.credId</code> <mark style="color:red;">*</mark></td><td><code>String</code></td><td>base64url encoded id of the credential. Note: This can be any unique value that identifies the credential (eg. account+key ID on AWS, the key's database ID, or the path to the key on disk)</td></tr><tr><td><code>credentialInfo.clientData</code> <mark style="color:red;">*</mark></td><td><code>String</code></td><td>base64url encoded <a href="/pages/JxGDccxJ5ryH9AWX6OAe#key-password-protected-key-and-recovery-credential">Client Data</a> JSON string object that was signed with the user's private key</td></tr><tr><td><code>credentialInfo.attestationData</code> <mark style="color:red;">*</mark></td><td><code>String</code></td><td>base64url encoded <a href="/pages/JxGDccxJ5ryH9AWX6OAe#key-password-protected-key-and-recovery-credential-1">Attestation Data</a> JSON string object with the users signature and public key</td></tr><tr><td><code>encryptedPrivateKey</code></td><td><code>String</code></td><td>Encrypted private key. The user should hold the secret to decrypting this value, and that secret should never be transmitted to Dfns</td></tr></tbody></table>

#### Example

```json
{
  "challengeIdentifier":"eyJ0e...fQNA",
  "credentialName": "My Recovery Credential",
  "credentialKind":"PasswordProtectedKey",
  "credentialInfo":{
    "credId":"GMkW0zlmcoMxI1OX0Z96LL_Mz7dgeu6vOH5_TOeGyNk",
    "clientData":"eyJ0eXBlIjoia2V5LmNyZWF0ZSIsImNoYWxsZW5nZSI6Ik1XTTBNbVk1WVRRME1EUmlOemRoTlRGaE56WTVPRFF3TldJNVpUUTRZMlJoT0RaaU5EazNaVFl6T1RFNU9HWXlNRGN4WmpCall6azRNbVE1WXpZMU1BIiwib3JpZ2luIjoiaHR0cHM6Ly9hcHAuZGZucy5uaW5qYSIsImNyb3NzT3JpZ2luIjpmYWxzZX0",
    "attestationData":"eyJjaGFsbGVuZ2UiOiJZMmd0Tm1Oc2RHTXRiV05sWTNZdE9XRTRPV2QxYnpKd1lqYzBOVEp4Y2ciLCJjcm9zc09yaWdpbiI6ZmFsc2UsIm9yaWdpbiI6Imh0dHBzOi8vYXBwLmRmbnMud3RmIiwidHlwZSI6ImtleS5jcmVhdGUifQ"
  },
  "encryptedPrivateKey":"LsXVskHYqqrKKxBC9KvqStLEmxak5Y7NaboDDlRSIW7evUJpQTT1AYvx0EsFskmriaVb3AjTCGEv7gqUKokml1USL7+dVmrUVhV+cNWtS5AorvRuZr1FMGVKFkW1pKJhFNH2e2O661UhpyXsRXzcmksA7ZN/V37ZK7ITue0gs6I="
}
```

### Recovery Credential

<table><thead><tr><th></th><th width="106.33333333333331"></th><th></th></tr></thead><tbody><tr><td><code>credentialKind</code> <mark style="color:red;">*</mark></td><td><code>String</code></td><td>will always be <code>RecoveryKey</code></td></tr><tr><td><code>credentialInfo</code> <mark style="color:red;">*</mark></td><td><code>Object</code></td><td>See fields below</td></tr><tr><td><code>credentialInfo.credId</code> <mark style="color:red;">*</mark></td><td><code>String</code></td><td>base64url encoded id of the credential</td></tr><tr><td><code>credentialInfo.clientData</code> <mark style="color:red;">*</mark></td><td><code>String</code></td><td>base64url encoded <a href="/pages/JxGDccxJ5ryH9AWX6OAe#key-password-protected-key-and-recovery-credential">Client Data</a> JSON string object that was signed with the user's private key</td></tr><tr><td><code>credentialInfo.attestationData</code> <mark style="color:red;">*</mark></td><td><code>String</code></td><td>base64url encoded <a href="/pages/JxGDccxJ5ryH9AWX6OAe#key-password-protected-key-and-recovery-credential-1">Attestation Data</a> JSON string object with the users signature and public key</td></tr><tr><td><code>encryptedPrivateKey</code></td><td><code>String</code></td><td>Encrypted private key. The user should hold the secret to decrypting this value, and that secret should never be transmitted to Dfns</td></tr></tbody></table>

#### Example

```json
{
  "challengeIdentifier":"eyJ0e...fQNA",
  "credentialName": "My Recovery Credential",
  "credentialKind":"RecoveryKey",
  "credentialInfo":{
    "credId":"GMkW0zlmcoMxI1OX0Z96LL_Mz7dgeu6vOH5_TOeGyNk",
    "clientData":"eyJ0eXBlIjoia2V5LmNyZWF0ZSIsImNoYWxsZW5nZSI6Ik1XTTBNbVk1WVRRME1EUmlOemRoTlRGaE56WTVPRFF3TldJNVpUUTRZMlJoT0RaaU5EazNaVFl6T1RFNU9HWXlNRGN4WmpCall6azRNbVE1WXpZMU1BIiwib3JpZ2luIjoiaHR0cHM6Ly9hcHAuZGZucy5uaW5qYSIsImNyb3NzT3JpZ2luIjpmYWxzZX0",
    "attestationData":"eyJjaGFsbGVuZ2UiOiJZMmd0Tm1Oc2RHTXRiV05sWTNZdE9XRTRPV2QxYnpKd1lqYzBOVEp4Y2ciLCJjcm9zc09yaWdpbiI6ZmFsc2UsIm9yaWdpbiI6Imh0dHBzOi8vYXBwLmRmbnMud3RmIiwidHlwZSI6ImtleS5jcmVhdGUifQ"
  },
  "encryptedPrivateKey":"LsXVskHYqqrKKxBC9KvqStLEmxak5Y7NaboDDlRSIW7evUJpQTT1AYvx0EsFskmriaVb3AjTCGEv7gqUKokml1USL7+dVmrUVhV+cNWtS5AorvRuZr1FMGVKFkW1pKJhFNH2e2O661UhpyXsRXzcmksA7ZN/V37ZK7ITue0gs6I="
}
```

## 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 describing the new credential

```json
{
  "credentialId": "c1QEdgnPLJargwzy3cbYKny4Q18u0hr97unXsF3DiE8",
  "credentialUuid": "cr-34514-nip9c-8bppvgqgj28dbodrc",
  "dateCreated": "2023-01-11T19:05:06.773Z",
  "isActive": true,
  "kind": "Fido2",
  "name": "My Yubikey",
  "publicKey": "SHA256:E2a3ZQEb4...rPqc",
  "relyingPartyId": "dfns.ninja",
  "origin": "https://app.dfns.ninja"
}
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs-legacy.dfns.co/d/api-docs/authentication/credential-management/api-reference/createusercredential-1.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.