Create Credential

POST /auth/credentials

Part of the flow Create Credential Regular flow.

Adds a new credential to a user's account. See Credential Kinds for all supported credential types.

User action signature required. See User Action Signing for more information.
Request headers required. See Request Headers for more information.
Authentication required. See Authentication Headers for more information.

Required Permissions

The permissions apply to the application only.

Name

Conditions

Auth:Creds:Create

Always Required

Request body

Field

Type

Description

challengeIdentifier *

String

Challenge identifier returned by the Create User Credential Challenge call

credentialName *

String

Name the user is assigning to this credential

credentialKind *

String

Kind of credential being registered (see Credential Kind)

credentialInfo *

Object

An object containing information about the credential being registered

encryptedPrivateKey

String

Only for Password Protected Key and Recovery Key

Fido2 Credential

credentialKind *

String

will always be Fido2

credentialInfo *

Object

See fields below

credentialInfo.credId *

String

base64url encoded id of the credential

credentialInfo.clientData *

String

base64url encoded client data object. The underlying object is the clientData object returned by the user's WebAuthn client

credentialInfo.attestationData *

String

base64url encoded attestation data object. The underlying object is the attestationData object returned by the user's WebAuthn client

Example

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

Key Credential

credentialKind *

String

will always be Key

credentialInfo *

Object

See fields below

credentialInfo.credId *

String

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)

credentialInfo.clientData *

String

base64url encoded Client Data JSON string object that was signed with the user's private key

credentialInfo.attestationData *

String

base64url encoded Attestation Data JSON string object with the users signature and public key

Example

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

Password Protected Key Credential

credentialKind *

String

will always be PasswordProtectedKey

credentialInfo *

Object

See fields below

credentialInfo.credId *

String

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)

credentialInfo.clientData *

String

base64url encoded Client Data JSON string object that was signed with the user's private key

credentialInfo.attestationData *

String

base64url encoded Attestation Data JSON string object with the users signature and public key

encryptedPrivateKey

String

Encrypted private key. The user should hold the secret to decrypting this value, and that secret should never be transmitted to Dfns

Example

{
  "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

credentialKind *

String

will always be RecoveryKey

credentialInfo *

Object

See fields below

credentialInfo.credId *

String

base64url encoded id of the credential

credentialInfo.clientData *

String

base64url encoded Client Data JSON string object that was signed with the user's private key

credentialInfo.attestationData *

String

base64url encoded Attestation Data JSON string object with the users signature and public key

encryptedPrivateKey

String

Encrypted private key. The user should hold the secret to decrypting this value, and that secret should never be transmitted to Dfns

Example

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

Responses

See Common Errors for common errors.
See Credential Management Errors for credential management specific errors.

Success - an object describing the new credential

{
  "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"
}

Last updated 1 month ago