Skip to main content
All API requests to DHMAD require authentication using an API key. This guide explains how to authenticate your requests.

​
API Key Authentication

DHMAD uses API key authentication. Each request must include your API key using one of the methods below.

​
Getting Your API Key

  1. Log into the Developer Dashboard
  2. Navigate to the “API Keys” section
  3. Create a new API key or use an existing one
  4. Copy the key (it’s only shown once!)

​
Using Your API Key

You can authenticate using either method: Include your API key in the Authorization header as a Bearer token: 
Authorization: Bearer sk_live_your_api_key_here

​
Method 2: X-API-Key Header

Include your API key in the X-API-Key header: 
X-API-Key: sk_live_your_api_key_here

​
Example Requests

curl -X GET https://dhmad.tn/api/v1/escrows \
  -H "Authorization: Bearer sk_live_abc123..." \
  -H "Content-Type: application/json"

​
API Key Format

API keys follow this format:
  • Live keys: sk_live_ followed by 64 hex characters — for production (https://dhmad.tn/api)
  • Sandbox keys: sk_sandbox_ followed by 64 hex characters — for the sandbox (https://sandbox.dhmad.tn/api)
Use each key only with its matching environment. A live key on the sandbox API (or a sandbox key on the production API) returns 401 Unauthorized.

​
Account Association

Most API operations require your developer account to be associated with a user account (e.g., checking balance, listing escrows, getting escrow details). The GET /me endpoint works without association. Creating escrows with sellerEmail also does not require association. You can associate your account in the developer dashboard.

​
Security Best Practices

Store Securely

Never commit API keys to version control. Use environment variables or secret management services.

Rotate Regularly

Regenerate your API keys periodically for better security.

Use Different Keys

Use separate API keys for development, staging, and production environments.

Monitor Usage

Regularly check your API key usage in the dashboard for any suspicious activity.

​
Error Responses

​
401 Unauthorized

If your API key is missing or invalid, you’ll receive a 401 error: 
{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}

​
403 Forbidden

If your API key is valid but your developer account is not associated with a user account: 
{
  "error": "Forbidden",
  "message": "Developer account must be associated with a user account to use this endpoint. Please associate your account in the developer dashboard."
}
Solution: Associate your developer account with a user account in the developer dashboard.

​
Rate Limiting

API requests are subject to rate limits:
  • Default: 100 requests per minute per IP address
  • Custom limits: You can set a custom rate limit when creating or updating an API key
  • Exceeding limit: Returns 429 Too Many Requests
The default rate limit applies per IP address. If you need higher limits, contact support@dhmad.tn

​
Testing Your Authentication

You can test your API key by making a simple request to the balance endpoint: 
curl -X GET https://dhmad.tn/api/v1/balance \
  -H "Authorization: Bearer your_api_key_here"
If successful, you’ll receive your account balance. If not, check that:
  • Your API key is correct
  • The key is active (not revoked)
  • Your developer account is associated with a user account
Never share your API keys publicly or commit them to version control. If a key is compromised, revoke it immediately in the dashboard and generate a new one.