Skip to main content
User Credentials are used to sign any API call that requires user signature. Most API requests (non-readonly requests mostly) require such a signature. Credentials can be of different kinds (see below), but are essentially all a public/private keypair. The private part is only known and kept by the user. The public key is shared with Dfns, so Dfns can validate the signature produced by the private key.

​
Credential kinds

  • Fido2 (Passkeys / WebAuthn). Recommended for human users. Uses the WebAuthn standard to create and store passkeys on the user’s device. Passkeys are tied to a domain name that must be whitelisted in your Dfns dashboard.
  • Key. A raw public/private keypair, primarily for Service Accounts. You generate and store the keypair yourself. See Generate a Key Pair.
  • PasswordProtectedKey. Like a Key credential, but the private key is stored by Dfns in encrypted form. Dfns never has the password. Encryption and decryption must happen on the frontend so you never access the decrypted key. During login and signing, the API returns the encryptedPrivateKey for the user to decrypt locally.
  • RecoveryKey. Like a Key credential, but designed for account recovery. The user safekeeps a human-readable recovery code. When used, all other credentials are invalidated. See Implementing end-user recovery.
Not all identity types support all credential kinds:
IdentityWebAuthn (Fido2)Key
UserYesYes
PAT (Personal Access Token)NoYes
Service AccountNoYes

​
Redundancy

Users can register multiple credentials, and this is recommended. If a user loses access to one credential (e.g. a lost phone), they can still authenticate with another. Register credentials on separate devices (e.g. laptop and a YubiKey) for resilience.

​
Credential Signature Flow

Most API requests (non-readonly requests mostly) require the signature from a valid Credential owned by the User. The credential signature flow usually looks like:
  1. User calls a first endpoint to get a challenge back (some cypher text that needs to be signed)
  2. User sign the challenge using a valid credential
  3. User calls a second endpoint to submit the signature
Different types of challenges that can be requested by a User:
  • A Registration Challenge (to register the first user credential, when user registers)
  • A Login Challenge (to login and get an auth token)
  • A User Action Challenge (required by most non-readonly API calls)
  • A Credential Challenge (used to create a new Credential)

​
Credential Creation Flows

There are two possible flows to create a new Credential for a User. The flow you will choose depend on where the User is (which app), and whether he has access access to his existing credential from this place.

​
Regular flow

This flow requires the last call (registration of the new credential) to be signed by an existing valid credential. That means that the user needs to have an existing credential accessible from the place where he’s adding a new credential.
  1. Call Create Credential Challenge to get a “Credential challenge” back. This endpoint does not require a user-action-signature required, so no credential signature involved here.
  2. Create a new credential locally, sign the above challenge with it.
  3. Call Create Credential to complete. This endpoint requires a User Action Flow, so it involves signing first with an existing valid credential to get an user action token.

​
Create Credential With Code flow

This flow requires the first call to be signed by an existing valid credential (creating the code). From then, the last steps can be performed without signature from a valid credential. This flow is useful when you want a user to create a new Credential from an app which doesn’t have access to the existing valid credential (since passkeys are tied to the domain name, they cannot be used “cross-domain”, eg. a passkey registered on domain www.app-1.com cannot be used inside the app www.app-2.com)
  1. In App 1, call Create Credential Code to get a one-time code. The code will only be valid for 1 minute. This endpoint requires a User Action Flow, so it involves signing first with an existing valid credential to get an user action token.
  2. In App 2, call Create Credential Challenge With Code (passing the code from step 1) to get a “Credential challenge” back
  3. In App 2, create a new credential locally, sign the above challenge with it.
  4. In App 2, call Create Credential With Code to complete (passing the code from step 1). This endpoint does not require a user-action-signature required, so no credential signature involved here
This demo video showcases this flow and how you could implement it in your product.

​
Key Creds vs WebauthN creds

Key credentials give extra flexibilty over WebAuthn to design signing to meet your needs. For example, you could choose to have a key without a passphrase (disabling MFA), to support scenarios where you don’t want the user to have to interact with your application to sign a transaction. Or, as another example, you could build an integration with an authentication device that is not supported by WebAuthn.

​
Security of Key Based Credentials

It is recommended that a user’s credentials never leave their system or device. This ensures that the credentials cannot be phished and that you as a service provide never have access to use the key on behalf of the user. If you are storing the key in the user’s browser. We recommend using a Service Worker to perform all cryptographic operations in a secure context.

​
Performing Actions on Behalf of your User

If you (your server) need to perform an action in a user’s wallet on behalf of your user, we recommend creating a Personal Access Token in your user’s account, rather than registering a credential (in your control) for your user. This allows the user to restrict the actions you are allowed to perform, and they can time-bound your access.

​
Credential object

​
kind
enum<string>
required
Available options:
Fido2,
Key,
Password,
Totp,
RecoveryKey,
PasswordProtectedKey
​
credentialId
string
required
​
credentialUuid
string
required
​
dateCreated
string
required
​
isActive
boolean
required
​
name
string
required
​
publicKey
string
required
​
relyingPartyId
string
required
​
origin
string
required
Last modified on April 16, 2026