Registration flows

How DFNS handles user, employee, and end-user registration, including standard registration, delegated registration, and social signup flows.

When new users are created within your organization with direct registration, they receive a registration email containing a registration code. Users created with delegated registration receive no email from DFNS: you run their registration from your application. These endpoints allow the user to complete the registration process.

This registration process includes registering the user’s authentication method. Either:

• WebAuthn (Passwordless MFA)
• a custom Key (public key of a public/private keypair) if this user will only interact programatically.

​

Regular users registration flow

1. Invite the user

   If you are running an existing organization, then you need to invite the new user to join you. Use (Create User) to add the new users. They will receive an email from DFNS with a registration code they will need to provide in the next step.

   If you have done that before and the code has expired, you can use (Resend Registration Code) to send a new registration code.

2. Create a user registration challenge

   Use providing the user’s registration code.

   DFNS will verify the registration code sent to the user, and generate a challenge to be signed and passed to the second endpoint. A temporary authentication token is also sent back, to be passed in the Authorization: Bearer [temporary token] header of the next registration endpoint.

3. Get the user to sign the challenge

   Depending on the type of credentials being used, the challenge can be signed in different ways:

   • passkey: the browser or the OS will handle the signing operation using WebAuthn APIs by creating a new passkey on the user device.
   • personal access token: the private key associated with the token can be used to sign the challenge.
   • service account token: the private key associated with the service account can be used to sign the challenge.
   • password-protected key: generate a keypair on the frontend, sign the challenge with the private key, then encrypt that private key with the user’s password. You submit both the signature and the resulting encryptedPrivateKey in the next step. DFNS stores the encrypted key and never receives the password or the decrypted key. See Implement password-protected keys for a full walkthrough with code.
4. Complete the user registration

   Use : Register.

   Here you will register an authentication method, and send the previous challenge with a signature.

   The type of credentials being registered is determined by the credentialKind field in the nested objects (firstFactorCredential, secondFactorCredential and RecoveryCredential). Supported credential kinds are:

   • Fido2: User action is signed by a user’s signing device using WebAuthn.
   • Key: User action is signed by a user’s, or token’s, private key.
   • PasswordProtectedKey: User action is signed by a user’s, or token’s, private key. The completion call includes an encryptedPrivateKey field: DFNS stores this encrypted key and returns it during the login and signing flows for the user to decrypt locally. DFNS never has the password.
   • RecoveryKey : Similar to PasswordProtectedKey, but this credential can only be used to recover an account not to sign an action or login. Once this credential is used all the other user’s credentials are invalidated.

​

Social registration flow

1. Send a registration code

   Use to initiate the social login process and get a challenge for the user to sign.

   See Create Social Registration Challenge for more details.

2. Follow the next steps to complete the social registration process as explained above.

​

Delegated users registration flow

With delegated registration, you verify the user’s identity in your application, and your service account registers the user with DFNS. The user receives no email from DFNS. Delegated registration is a registration mode, not a user kind: it is available for end users (EndUser) and, on-demand, for employees (CustomerEmployee). It only changes how the user registers and recovers their account. Once registered, the user has the same access as any other user of the same kind.

1. Create the user

   Use : Create User with registration: "Delegated". End users always use delegated registration. Delegated registration for employees is available on-demand.

   For end users, you can skip this step: the next step creates the end user if it does not exist yet. This behavior is kept for backward compatibility.

2. Create the registration challenge

   Use : Create Delegated Registration Challenge with the user’s email and kind. It initiates a first credential registration for the user and returns the registration challenge.

3. Get the user to create a passkey

   Send the registration challenge to your frontend so the user can create a Fido2 passkey.

   The device or the browser will prompt the user to create a passkey (e.g.: using a fingerprint reader, a pin code, etc.).

   When the user has completed the creation, you obtain the signed challenge in return. You will need to use the returned signature in the next step.

4. Complete the registration

   Finally, you can either call:

   • : the Register endpoint to complete the user’s registration.
   • : the Register End User endpoint to complete the registration and create wallets for that user in one go. End users only.

   All credentials sent in the completion call (firstFactorCredential, secondFactorCredential, recoveryCredential) sign the same challenge returned by the init endpoint in the previous step.

Bundle a recoveryCredential in the completion call. Without one, a user who loses their device cannot recover access and you will have to handle every case manually via delegated recovery. See Implement end-user recovery.

For a complete implementation guide with code examples, see Implementing delegated wallets.