Dfns API Documentation
  • 👋Welcome
  • Getting Started
    • Onboarding to Dfns
    • Dfns Environments
    • Core API Objects
    • Supported Assets
    • Postman
    • Dfns SDKs
    • Dashboard Videos
  • API Docs
    • Introduction
    • Authentication
      • Delegated Authentication
        • Delegated Registration
        • Delegated Registration Restart
        • Delegated Login
      • User Action Signing
        • Create User Action Signature Challenge
        • Create User Action Signature
      • Registration
        • Create User Registration Challenge
        • Complete User Registration
        • Complete End User Registration with Wallets
        • Resend Registration Code
        • Social Registration
      • Login
        • Create User Login Challenge
        • Complete User Login
        • Social Login
        • Logout
        • Send Login Code
      • Users
        • List Users
        • Create User
        • Get User
        • Activate User
        • Deactivate User
        • Archive User
      • Service Accounts
        • List Service Accounts
        • Create Service Account
        • Get Service Account
        • Update Service Account
        • Activate Service Account
        • Deactivate Service Account
        • Archive Service Account
      • Applications
        • List Applications
        • Create Application
        • Create Server-Signed Application
        • Get Application
        • Update Application
        • Activate Application
        • Deactivate Application
        • Archive Application
      • Personal Access Tokens
        • List Personal Access Tokens
        • Create Personal Access Token
        • Get Personal Access Token
        • Update Personal Access Token
        • Activate Personal Access Token
        • Deactivate Personal Access Token
        • Archive Personal Access Token
      • Credentials
        • Credentials Overview
        • API Reference
          • Create Credential Code
          • Create Credential Challenge
          • Create Credential Challenge With Code
          • Create Credential
          • Create Credential With Code
          • Deactivate Credential
          • Activate Credential
          • List Credentials
      • Recovery
        • Send Recovery Code Email
        • Create Recovery Challenge
        • Create Delegated Recovery Challenge
        • Recover User
    • Wallets
      • Create Wallet
      • Update Wallet
      • Delete Wallet
      • [deprecated] Delegate Wallet
      • Get Wallet by ID
      • List Wallets
      • Get Wallet Assets
      • Get Wallet NFTs
      • Get Wallet History
      • Tag Wallet
      • Untag Wallet
      • Transfer Asset
      • Get Transfer Request by ID
      • List Transfer Requests
      • Sign and Broadcast Transaction
        • Algorand
        • Aptos
        • Bitcoin / Litecoin
        • Canton
        • Cardano
        • EVM
        • Solana
        • Stellar
        • Tezos
        • TRON
        • XRP Ledger (Ripple)
      • Get Transaction Request by ID
      • List Transaction Requests
      • [deprecated] Generate Signature
      • Advanced Wallet APIs
        • Import Wallet
        • [deprecated] Export Wallet
    • Fee Sponsors
      • Create Fee Sponsor
      • Get Fee Sponsor
      • List Fee Sponsors
      • Activate Fee Sponsor
      • Deactivate Fee Sponsor
      • Delete Fee Sponsor
      • List Sponsored Fees
    • Keys
      • Create Key
      • Update Key
      • Delete Key
      • Delegate Key
      • Get Key by ID
      • List Keys
      • Generate Signature
        • Algorand
        • Aptos
        • Bitcoin / Litecoin
        • Cardano
        • Cosmos Appchain
        • EVM
        • Solana
        • Stellar
        • Substrate (Polkadot)
        • Tezos
        • TON
        • TRON
        • XRP Ledger (Ripple)
      • Get Signature Request by ID
      • List Signature Requests
      • Advanced Key APIs
        • Import Key
        • Export Key
        • Deterministic Derivation
    • Networks
      • Estimate fees
      • Read Contract
      • Validators
        • Create Validator
        • List Validators
    • Policy Engine
      • Policies Overview
      • API Reference
        • Create Policy
        • Get Policy
        • List Policies
        • Update Policy
        • Archive Policy
        • Get Approval
        • List Approvals
        • Create Approval Decision
    • Permissions
      • Permissions Overview
      • API Reference
        • Get Permission
        • List Permissions
        • Create Permission
        • Update Permission
        • Archive Permission
        • Assign Permission
        • Revoke Permission
        • List Permission Assignments
    • Webhooks
      • Create Webhook
      • Get Webhook
      • List Webhooks
      • Update Webhook
      • Delete Webhook
      • Ping Webhook
      • Get Webhook Event
      • List Webhook Events
    • Dfns Change Log
    • API Errors
  • Integrations
    • Exchanges
      • Kraken
      • Binance
      • Coinbase Prime
      • API Reference
        • Create Exchange
        • List Exchanges
        • Get Exchange
        • Delete Exchange
        • List Exchange Accounts
        • List Exchange Account Assets
        • Create Exchange Deposit
        • Create Exchange Withdrawal
    • AML / KYT
      • Chainalysis
    • Staking
      • API Reference
        • Create Stake
        • Create Stake Action
        • List Stakes
        • List Stake Actions
        • get Rewards
    • Fiat On/Off-Ramps
    • Account Abstraction on EVMs
  • Advanced Topics
    • Authentication
      • API Authentication
      • Request Headers
      • Credentials
        • Generate a Key Pair
        • User Credentials
        • Access Token Credentials
        • Storing WebAuthn Credentials in Password Managers
      • Request Signing
      • API objects
    • Delegated Signing
    • API Idempotency
    • FAQ
  • Guides
    • Passkey Settings - Migration guide
    • Keys & Multichain - Migration Guide
Powered by GitBook
On this page
  • Get an authentication token
  • Sign API requests (User Action Signing)
  • Credentials
  1. Advanced Topics
  2. Authentication

API Authentication

Last updated 3 months ago

To use Dfns API endpoints, you will generally need to:

  1. Get an authentication token (referred to as "authentication token" or "token").

  2. Sign a User Action Challenge using a cryptographic key that you own (referred to "Credential Key" or just "Credentials"). This is only required for actions which mutate state (non-readonly api calls).

Check Request Headers for more details about which headers are required

Get an authentication token

There are several ways to get an authentication token, depending on what kind of "identity" you'll be using. You can authenticate as:

  • A User (human )

  • A Service Account (machine )

As a User, there are two ways to get an authentication token:

  • Follow the flow. You'll get a authentication token at the end of this flow, which expires after a relatively short period of time.

  • Or create a (PAT), which basically is a long-lived authentication token which is tied to the User and represents them. This PAT will never have more permissions than the User itself. Once you have created a PAT, you can use it as an authentication token directly.

A (or "Service Account") is not tied to one User, it's existence is visible across all your organisation. It is a long-lived token, and any permission can be granted to it, beyond the scope of one particular user. Once created, this Service Account can be used as an authentication token directly.

Once generated, Dfns system do not keep a trace of your long-lived authentication tokens (Personal Access Token, or Service Account Token), only you will hold on to those. If you lose them, you'll just need to create a new one.

Once you have an authentication token, you can add it in the headers of your API requests as an Bearer token: Authorization: Bearer {auth_token}.

Sign API requests (User Action Signing)

Most endpoints which induce some state change in Dfns (everything that is not a GET essentially), will require you to sign the actual request, before being able to execute it. We call that "User Action Signing".

  • You tell Dfns "I want to perform this exact request"

  • Dfns sends you back a challenge to be signed with your Credential .

  • You sign the challenge with your Credentials (essentially a cryptographic key you registered), and send it to Dfns.

  • Dfns gives you back a "user action signature", which you'll need include in the headers when you perform the actual request (X-DFNS-USERACTION header)

The credential -- essentially being a cryptographic key -- you'll need to use to sign the challenge will depend on who is calling the api (User / Service Account), see more about that below.

Credentials

In order to complete the Login flow, or sign User Action Challenges, users need to sign "challenges" using their Credential.

A Credential is essentially a public/private cryptographic keypair. The private key is held by the user, while the public key is provided to Dfns to register the credential for the user.

The first time you registered on Dfns dashboard, you created a Passkey credential. You can also register additional credentials later on using our API.

Different kind of Credentials can be created, depending on your use case, and how you prefer to manage them:

  • Fido2 Credentials (aka "Passkeys" / "WebAuthn") -> Uses WebAuthn standard to create/manage passkeys on your device (see more about that below). You can use passkeys if you need a client-side User signature (eg. in a web app / native app).

Depending on the Identity you are using, the Credentials supported are such:

Identity
WebAuthn Credentials
Key Credentials

User

PAT (Personal Access Token)

Service Account

Passkeys

Passkeys is the common term used to describe the Fido2 standard called "WebAuthn". It is a web authentication standard supported by most modern browsers, phones and devices, which leverages your devices key-management features (like touch ID on a mac, a phone authenticator, a yubikey, some password managers support creating and storing passkeys, etc).

Thos passkeys can then be used by the user to sign payloads when needed. Here's some screenshots with some examples of WebAuthn prompts shown in your browser during Credential creation, or during Signing using those Credentials.

Below is an example of the promps a user can see on a web app, when a challenge needs to be signed with the passkey: it's asking the user for his biometrics (fingerprint) before using the passkey to sign.

We provide a couple of endpoints which handle this flow:

Key Credentials -> "manually" generate keypairs yourself, and store them however you see fit (see ). You can use Key Credential if you need a Service Account sitting in your server to also be the signer for example.

You can read more about WebAuthn on , and if you want you can test a WebAuthn demo on

👨
🤖
Login
Personal Access Token
Service Account Token
User Action Signing
How to generate a keypair
webauthn.guide
webauthn.io
✅
✅
🛑
✅
🛑
✅