Required headers

Authentication token

The following sections explain how these headers work and how to obtain them.

An authentication token
A user action signature for state changing requests

To authenticate API requests, you must include a Bearer token in the Authorization header.

Header	Description
Authorization: Bearer `<token>`	Authentication token used to authorize the request.

You can obtain a token in one of the following ways:

As a user (human):

Login flow: After completing the login flow, you receive an authentication token with a short expiration time.
Personal Access Token (PAT): A PAT is a long lived authentication token you generate manually. You can use it directly in the Authorization header.

As a service account (machine):

Service Account Token: A service account can generate a long lived token that you can use directly in the Authorization header.

Note: During user registration, the first step returns a temporary registration token. Use this token as a Bearer token in the Authorization header for the next registration step.

User action signature

For API calls that change system state (for example POST, PUT, DELETE requests), you must also include a one time signature in the X-DFNS-USERACTION header. This process is called User Action Signing.

Header	Description
X-DFNS-USERACTION: `<user-action-signature>`	One time signature for state changing requests.

How user action signing works

You tell IBM Digital Asset Haven the exact request you want to perform.
IBM Digital Asset Haven returns a challenge that must be signed using your credential key.
You sign the challenge using your credentials.
IBM Digital Asset Haven returns a user action signature.
You include that signature in the X-DFNS-USERACTION header when making the actual request.

Getting current user info

IBM Digital Asset Haven does not provide a /me or /whoami endpoint. Instead, decode the JWT token to retrieve user information. You can use jwt.io for debugging or a JWT library in your application.

Decoding the token (example using jose):

// Using jose library
import { decodeJwt } from 'jose'

const token = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...'
const payload = decodeJwt(token)

const userId = payload['https://custom/app_metadata'].userId
const orgId = payload['https://custom/app_metadata'].orgId
const email = payload['https://custom/username']

Example decoded token:

{
  "iss": "auth.api.digitalassets.ibm.com",
  "aud": "dfns:auth:user",
  "sub": "or-xxxxx-xxxxx-xxxxxxxxxxxxxxxx",
  "jti": "uj-xxxxx-xxxxx-xxxxxxxxxxxxxxxx",
  "https://custom/username": "user@example.com",
  "https://custom/app_metadata": {
    "tokenKind": "Token",
    "userId": "us-xxxxx-xxxxx-xxxxxxxxxxxxxxxx",
    "orgId": "or-xxxxx-xxxxx-xxxxxxxxxxxxxxxx"
  },
  "iat": 1767947321,
  "exp": 1767968921
}

Token fields:

Field	Description
`https://custom/username`	The user’s email address
`https://custom/app_metadata.userId`	The user ID
`https://custom/app_metadata.orgId`	The organization ID
`exp`	Token expiration time in Unix timestamp format

Common errors

401 Unauthorized

Occurs when the Authorization header is missing, malformed, or contains an invalid or expired token.

Solutions:

Verify the header follows the format Authorization: Bearer <token>.
Check that the token has not expired. Decode it and inspect the exp field.

403 User action signature is missing

Occurs when you call a state changing endpoint without including the X-DFNS-USERACTION header .

Solutions:

Complete the User Action Signing flow to obtain a signature.
In Postman, ensure the pre request script is configured correctly.
In SDKs, ensure you have set up a signer for the underlying credential.

Note: GET requests do not require the X-DFNS-USERACTION header. If you see this error, you are likely making a state changing request.

Attention: Once generated, IBM Digital Asset Haven does not store your Service Account Token or Personal Access Token. You are responsible for keeping them secure. If you lose a token, you must create a new one.