Skip to main content
Welcome to Dfns! This guide will walk you through the foundational authentication concepts you need to start making API calls. Understanding how Dfns handles security is the key to a successful integration. The core of our security model relies on a two-token system for sensitive operations: an Authentication Token to authenticate your application, and a User Action Signature to prove end-user consent.

🔑 Token 1: The Login Token

The Authentication Token is like your API key, proving that requests are coming from a legitimate source. You must include this token in the Authorization header for every API call.

How to Get It

Follow one of the authentication flows. The easiest way: create a service account and use it in your backend to call our API. This token answers the question: “Is my application allowed to talk to Dfns?
For a step-by-step guide on creating credentials and generating your first token, see the Dfns API using a service account tutorial.

✍️ Token 2: The User Action Signature

For any sensitive operation —like creating a key, initiating a transaction, or registering a wallet— you need a second token. The User Action Signature is a signed challenge that proves a user with a registered passkey has explicitly approved the action. This token is sent in the X-DFNS-USERACTION header and is required for most POST, PUT, and DELETE requests. Think of it like a bank transaction:
  • The Authentication Token is the bank teller’s ID, allowing them to access the banking system.
  • The User Action Signature is the customer’s signed withdrawal slip, authorizing a specific transaction.
The teller needs both to release the funds. Similarly, Dfns requires both tokens to ensure that a request is not only from a trusted application but is also explicitly authorized by the asset owner. This token answers the question: “Did the user consent to this specific action?
To learn how to generate and use this signature, see the detailed User Action Signature Guide.

Next Steps & Resources

Now that you understand the core authentication concepts, you’re ready to dive in.

Essential References

I