Skip to main content

​
OpenAPI

You can find the OpenAPI specification of the Dfns API here: OpenAPI Specification

​
Postman

The Dfns Postman collection lets you test API endpoints without writing code. It includes a pre-request script that automatically handles User Action Signing for state-changing requests (POST, PUT, DELETE). Run In Postman
You must fork the collection using the button above. Downloading or importing the collection manually may result in missing scripts or environment variables.

​
Setup

1

Generate a key pair

Generate an ECDSA key pair that will be used to sign requests:
# Generate private key
openssl ecparam -genkey -name prime256v1 -noout -out prime256v1.pem

# Extract public key
openssl pkey -in prime256v1.pem -pubout -out prime256v1.public.pem
Keep the private key file (prime256v1.pem) secure - you’ll need it in Step 3.
2

Create a Personal Access Token (PAT)

  1. Go to Settings > Personal Access Token in the Dfns Dashboard
  2. Click New Personal Access Token
  3. Paste the contents of prime256v1.public.pem into the Public Key field
  4. Click Create
After creation, copy the Auth Token (displayed once - copy it immediately). You’ll need it in the next step.
3

Configure the Postman environment

  1. In Postman, go to Environments in the left sidebar
  2. Select the Dfns API - Prod environment
  3. Fill in the Current Value column:
VariableValue
dfnsApiDomainAlready set to api.dfns.io. Change to api.uae.dfns.io if you’re using the UAE region. See Regions for details.
authTokenThe JWT token from Step 2
credentialPrivateKeyContents of prime256v1.pem (include the full key with newlines)
  1. Click Save
  2. Set this environment as Active using the dropdown in the top-right corner of Postman
When pasting credentialPrivateKey, include the entire key including -----BEGIN EC PRIVATE KEY----- and -----END EC PRIVATE KEY----- lines.
4

Verify the pre-request script

Before making requests, verify the pre-request script is present:
  1. Click on the Dfns API collection name in the left sidebar
  2. Go to the Scripts tab (or Pre-request Script in older Postman versions)
  3. You should see JavaScript code that handles User Action Signing
Pre-request script location in Postman
If the script is empty, see Troubleshooting below.
5

Test with a GET request

Start with a read-only request to verify your setup:
  1. Open Wallets > List Wallets (GET /wallets)
  2. Click Send
  3. You should receive a 200 response with your wallets list
If this works, your authentication is configured correctly.

​
How the pre-request script works

The pre-request script automatically handles User Action Signing for POST, PUT, and DELETE requests:
  1. Detects when you’re making a state-changing request
  2. Calls /auth/action/init to get a challenge
  3. Signs the challenge using your credentialPrivateKey
  4. Populates the X-DFNS-USERACTION header with the signed result
This means you don’t need to manually handle the challenge-response flow for each request.

​
Troubleshooting

​
Pre-request script is empty

If the Scripts tab shows no code:
  1. Re-fork the collection - Don’t import manually. Use the “Run in Postman” button above to fork the official collection.
  2. Check the collection level - The script is on the collection, not individual requests. Click the collection name, not a specific endpoint.
  3. Update Postman - Older versions may have issues with collection scripts.

​
403 “User action signature is missing”

This error means the pre-request script didn’t run or failed. Check:
  1. Environment is active - Verify your environment is selected in the top-right dropdown
  2. All variables have Current Values - Initial Value is not used; you must fill Current Value
  3. Private key format - Must include full PEM format with headers and newlines
  4. Check Postman Console - Go to View > Show Postman Console to see script errors

​
401 Unauthorized

  1. Verify authToken is correct (it’s a long JWT string)
  2. Check dfnsApiDomain matches your organization’s region
  3. Ensure the PAT hasn’t been revoked or expired. Decode your token at jwt.io and check the exp field for the expiry date.

​
Request hangs or times out

  1. Check dfnsApiDomain doesn’t include https:// (just use api.dfns.io)
  2. Verify you have network access to the Dfns API