Authentication

Authenticating API Requests

All DHUBiC API endpoints require authentication. We use industry-standard Bearer tokens (JWT) and OAuth 2.0 to secure every request. This guide walks you through obtaining credentials, adding auth headers, handling token expiry, and managing permission scopes.

Overview

DHUBiC supports two primary authentication mechanisms:

🔑

Bearer Token (JWT)

Short-lived tokens obtained by calling POST /api/login. Best for server-to-server integrations.

🔐

OAuth 2.0

Delegated access for third-party apps. Users authorise your app without sharing credentials.

ℹ️

All API traffic must be sent over HTTPS. Requests made over plain HTTP will be rejected with 400 Bad Request.

Bearer Token (JWT)

Attach your token in the Authorization header of every request:

Authorization:Bearer<your-token>

Tokens expire after 24 hours by default.
Workspace admins can configure shorter TTLs (down to 15 minutes).
Service accounts can request non-expiring tokens with restricted scopes.

Obtaining a Token

Call POST /api/login with your credentials. The response includes an access_token and a refresh_token.

// Request

{

"email": "you@company.com",

"password": "••••••••"

}

// Response 200 OK

{

"access_token": "eyJhbGciOiJSUzI1NiJ9...",

"refresh_token": "drt_01hwz3k9xm8j...",

"expires_in": 86400

}

Making Authenticated Requests

Include these headers on every API call:

Header	Required	Value
Authorization	Yes	Bearer <token>
Content-Type	Yes (POST/PUT)	application/json
Accept	No	application/json
X-Request-ID	No	UUID for idempotency

OAuth 2.0

Use OAuth 2.0 when building integrations that act on behalf of users. DHUBiC implements the Authorization Code flow with PKCE.

1
Redirect to DHUBiC
Send the user to the authorization endpoint with client_id, redirect_uri, scope, and PKCE challenge.
2
User authorises
DHUBiC shows a consent screen. On approval the user is redirected back with a one-time code.
3
Exchange for token
POST /accounts/auth/oauth/token with the code and PKCE verifier to receive access + refresh tokens.
4
Use the token
Include the access token in your Authorization header exactly like a password login token.
5
Refresh when needed
Before expiry, POST /accounts/auth/oauth/refresh with your refresh token to obtain a new pair.

Scopes & Permissions

When requesting OAuth access, specify the scopes your application needs:

Scope	Access
`payments:read`	View payments and beneficiaries
`payments:write`	Create and approve payments
`rates:read`	Read FX rates and rate history
`accounts:read`	View account balances and statements
`reporting:read`	Access reports and analytics
`workspace:admin`	Full workspace administration

Error Handling

Authentication failures return standard HTTP status codes:

401 Unauthorized

Token is missing, expired, or malformed. Re-authenticate to obtain a new token.

403 Forbidden

Token is valid but lacks the required scope. Request additional permissions.

429 Too Many Requests

Rate limit exceeded. Respect the Retry-After header returned in the response.

Rate Limits

Every API response includes rate limit headers:

X-RateLimit-Limit: 1000

X-RateLimit-Remaining: 987

X-RateLimit-Reset: 1717027200

Retry-After: 60

Default limit: 1,000 requests / minute per workspace. Contact support for higher limits.

SDK Quickstart

Authenticate and make your first request in under a minute:

# 1. Obtain a token
curl -s -X POST https://api.dhubic.com/v1/api/login \
  -H "Content-Type: application/json" \
  -d '{"email":"you@company.com","password":"••••••••"}' \
  | jq -r '.access_token'

# 2. Use the token
TOKEN="eyJhbGciOiJSUzI1NiJ9..."

curl https://api.dhubic.com/v1/payments \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

Ready to explore endpoints?

Browse the full API reference to see all available operations.

Browse API Reference →