User Action Signing flows

All API calls that make a change within the Dfns system need to be signed by a user. This ensures that only authorized users are able to make changes within the system, and the signature can be used to audit changes at a later time.

You can find more details in the developers guides section.

Fido2 signing flow

This flow is for a human user interacting with a frontend (website, mobile app, etc) and signing the request using his passkey from that frontend.

The authToken to use here is from that user, refer to the login flows for details how to obtain that token.

1. Prepare your endpoint call payload

   For starting a signing session you need to prepare the API call you intend to make eventually.

   As an example let’s use Transfer Asset.

   • Method: POST
   • Path: /wallets/wa-12345-12345-12345678910/transfers
   • Payload: {"kind": "Native", "to": "0xe5a2ebc128e262ab1e3bd02bffbe16911adfbffb", "amount": "100000"}

   Backend TypeScript SDK

   import { DfnsDelegatedApiClient } from '@dfns/sdk'
   
   const dfnsClient = new DfnsDelegatedApiClient({
     baseUrl: 'https://api.dfns.io', // base Url of DFNS API
     orgId: 'org-2ng9jv-80cfc-983pop0iauf2sv8r', // ID of the Dfns Organisation
     authToken: userAuthToken, // Auth token of the User
   })
   
   const payload = {
       kind: "Native", 
       to: "0xe5a2ebc128e262ab1e3bd02bffbe16911adfbffb", 
       amount: "100000"
     }
   

2. Request a User Action Challenge

   Use POST/auth/action/init: Create User Action Challenge.

   This starts a user action signing session, returning a challenge that will be used to verify the user’s intent to perform an action. You need to provide details about the intended call:

   Backend TypeScript SDK

   const challenge = await dfnsClient.wallets.transferAssetInit(payload)
   

3. Get the user to sign the challenge

   You need to forward the challenge and associated information to the frontend (browser or app) to handle the signing operation using WebAuthn APIs.

   Frontend TypeScript SDK

   import { WebAuthnSigner } from '@dfns/sdk-browser'
   const webauthn = new WebAuthnSigner({ relyingParty: { id: 'acme.com', name: 'Acme' } })
   
   const challenge = "Object coming from the backend"
   
   const signedChallenge = await webauthn.sign(challenge) // this call will trigger the request for interacting with the passkey
   
   // Forward signedChallenge back to the backend
   

4. Request a User Action token

   Use POST/auth/action. Refer to Create User Action Signature for endpoint details.

   Completes the user action signing process and provides a signing token that can be used to verify the user intended to perform the action.

   Backend TypeScript SDK

   const signedChallenge = "object coming back from the frontend"
   /*
   Requesting a token is hidden into 
   the function used in the next step
   */ 
   

5. Use the User Action token

   Add the User Action token to the X-DFNS-USERACTION header of the original API call that requires user action signing.

   Backend TypeScript SDK

   const transfer = await dfnsClient.wallets.transferAssetComplete(payload, signedChallenge)
   

Asymetric Keys signing flow

This flow is for machine-to-machine interactions: a backend signs the request using an asymetric key, there is no signing request to the user. The backend can login as a Service Account (machine user with its own identity), as a user using their Personal Access Token. Just provide the right token as authToken for all the following API calls.

You should also have registered the public key when you created the Service Account or the user’s Personal Access Token. The Private Key will be used to sign the challenges, make sure you use the private key linked to the authToken you are using!

1. Prepare your endpoint call payload

   For starting a signing session you need to prepare the API call you intend to make eventually.

   As an example let’s use Transfer Asset.

   • Method: POST
   • Path: /wallets/wa-12345-12345-12345678910/transfers
   • Payload: {"kind": "Native", "to": "0xe5a2ebc128e262ab1e3bd02bffbe16911adfbffb", "amount": "100000"}

   Backend TypeScript SDK

   import { DfnsApiClient } from '@dfns/sdk'
   import { AsymmetricKeySigner } from '@dfns/sdk-keysigner'
   
   const signer = new AsymmetricKeySigner({
     credId: 'X2ktMzhxaTEtZTF1bTgtOXY1cG9yY2tkZDe1dG1jYg', // Credential ID
     privateKey: CREDENTIAL_PRIVATE_KEY, // Credential private key
   })
   
   const dfnsClient = new DfnsApiClient({
     baseUrl: 'https://api.dfns.io', // base Url of DFNS API
     orgId: 'or-2ng9jv-80cfc-983pop0iauf2sv8r', // ID of the Dfns Organisation
     authToken: '...', // Service Account or PAT auth token
     signer,
   })
   
   const payload = {
       kind: "Native", 
       to: "0xe5a2ebc128e262ab1e3bd02bffbe16911adfbffb", 
       amount: "100000"
     }
   

2. Request a User Action Challenge

   Use POST/auth/action/init: Create User Action Challenge.

   This starts a user action signing session, returning a challenge that will be used to verify the user’s intent to perform an action. You need to provide details about the intended call:

   Backend TypeScript SDK

   // This step is hidden when you use the SDK.
   

3. Sign the challenge

   Use a crypto library or a KMS to sign the challenge.

   Backend TypeScript SDK

   // This step is hidden when you use the SDK.
   

4. Request a User Action token

   Use POST/auth/action. Refer to Create User Action Signature for endpoint details.

   Completes the user action signing process and provides a signing token that can be used to verify the user intended to perform the action.

   Backend TypeScript SDK

   // This step is hidden when you use the SDK.
   

5. Use the User Action token

   Add the User Action token to the X-DFNS-USERACTION header of the original API call that requires user action signing.

   Backend TypeScript SDK

   const transfer = await dfnsClient.wallets.transferAsset(payload)