Authenticating API Requests
Bearer tokens, OAuth 2.0 flows, scopes, token refresh, and rate limits. Everything you need to securely call any DHUBiC API endpoint.
Overview
DHUBiC supports two primary authentication mechanisms. Choose the one that fits your integration type:
Bearer Token (JWT)
Short-lived tokens obtained via POST /api/login. Best for server-to-server integrations and scripts.
OAuth 2.0
Delegated access for third-party apps. Users authorise your app without sharing credentials.
400 Bad Request.Bearer Token (JWT)
Attach your token in the Authorization header of every request:
- Tokens expire after 24 hours by default.
- Workspace admins can configure shorter TTLs (minimum 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 both an access_token and a refresh_token.
/api/loginRequest / ResponseRequest body
{
"email": "you@company.com",
"password": "••••••••"
}200 Response
{
"access_token": "eyJhbGci...",
"refresh_token": "drt_01hwz...",
"expires_in": 86400
}Making Authenticated Requests
Include these headers on every API call:
| Header | Required | Value |
|---|---|---|
Authorization | Yes | Bearer <token> |
Content-Type | 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.
Redirect to DHUBiC
Send the user to the authorization endpoint with client_id, redirect_uri, scope, and PKCE challenge.
User authorises
DHUBiC shows a consent screen. On approval the user is redirected back with a one-time authorization code.
Exchange for token
POST /accounts/auth/oauth/token with the code and PKCE verifier to receive access + refresh tokens.
Use the token
Include the access token in your Authorization header exactly like a password login token.
Refresh when needed
Before expiry, POST /accounts/auth/oauth/refresh with your refresh token to obtain a fresh pair.
Scopes & Permissions
Specify the minimum scopes your application needs when requesting OAuth access:
| Scope | Access granted |
|---|---|
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 with a JSON error body:
Token is missing, expired, or malformed. Re-authenticate to obtain a new token.
Token is valid but lacks the required scope. Request additional permissions from the workspace admin.
Rate limit exceeded. Back off and retry after the interval in the Retry-After response header.
{
"error": "unauthorized",
"message": "Token has expired",
"status": 401
}Rate Limits
Every API response includes rate limit headers. Default limit is 1,000 requests / minute per workspace.
X-RateLimit-Limit: 1000 X-RateLimit-Remaining: 987 X-RateLimit-Reset: 1717027200 Retry-After: 60
Retry-After before retrying. Repeated immediate retries will not restore the limit faster.SDK Quickstart
Authenticate and make your first API call 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.