API Authentication
To use Dfns API endpoints, you will generally need to:
Get an authentication token (referred to as "authentication token" or "token").
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).
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 Login 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 Personal Access Token (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 Service Account Token (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 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".
We provide a couple of User Action Signing endpoints which handle this flow:
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-USERACTIONheader)
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).
Key Credentials -> "manually" generate keypairs yourself, and store them however you see fit (see How to generate a keypair). You can use Key Credential if you need a Service Account sitting in your server to also be the signer for example.
Depending on the Identity you are using, the Credentials supported are such:
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.
Last updated