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.

200

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