Request Headers

All requests to the Dfns API need to include at least these headers:

Header	Description
X-DFNS-APPID: <appid>	ID of an Application created in your organization (see Applications)

Authentication Headers

Most requests to the Dfns API need to be authenticated, and will need to include the following additional headers:

Header	Description
Authorization: Bearer <token>	An authentication token (see Get an authentication token)

User Action Signing Header

Most requests that change the state within the Dfns system need to be signed (see User Action Signing), and require the following additional header:

Header	Description
X-DFNS-USERACTION: <user-action-signature>	A one time token you got after the User Action Signing flow

Registration Headers

Similar to authenticated endpoints, the Complete User Registration endpoint needs an authentication token. This token is passed in the Authentication header:

Header	Description
Authorization: Bearer <token>	The temporary authentication token returned from Responses

Server-Signed Application Headers

This is not a common scenario. Dfns recommends using a default Application for most use cases

App Secret and API Signature do not replace the authentication and user action signing requirements. For endpoints that need authentication you will still provide the Authorization header, and for endpoints that require user action signing, you will also still provide the X-DFNS-USERACTION header.

Application tokens do not grant access to the Dfns API, they are just used to enforce how the API is called

Server-signed applications can be used to ensure that all requests going to the Dfns API must originate from your servers. This is enforced by the caller providing an additional signature and an application secret (token) for the request, using the following additional headers:

Header	Description
X-DFNS-APPSECRET: <app-token>	A secret token that identifies the application that is calling the API
X-DFNS-APISIGNATURE: <api-signature>	The signature of the normalized request being made to the Dfns API
X-DFNS-NONCE: <nonce>	Random value used to prevent replay attacks. It must be a base64url-encoded JSON string with the following fields: - uuid - Random value of at least 13 characters - date - Current time of the request in ISO String format See below for a code example

The following Typescript code can be used to generate the nonce:

Buffer.from(
  JSON.stringify({
    uuid: v4(),
    date: new Date().toISOString(),
  })
).toString('base64url')