> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dhmad.tn/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Learn how to authenticate your API requests

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](https://developer.dhmad.tn/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:

#### Method 1: Bearer Token (Recommended)

Include your API key in the `Authorization` header as a Bearer token:

```bash theme={null}
Authorization: Bearer sk_live_your_api_key_here
```

#### Method 2: X-API-Key Header

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

```bash theme={null}
X-API-Key: sk_live_your_api_key_here
```

### Example Requests

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET https://dhmad.tn/api/v1/escrows \
    -H "Authorization: Bearer sk_live_abc123..." \
    -H "Content-Type: application/json"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://dhmad.tn/api/v1/escrows', {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer sk_live_abc123...',
      'Content-Type': 'application/json'
    }
  });
  ```

  ```python Python theme={null}
  import requests

  headers = {
      'Authorization': 'Bearer sk_live_abc123...',
      'Content-Type': 'application/json'
  }

  response = requests.get(
      'https://dhmad.tn/api/v1/escrows',
      headers=headers
  )
  ```

  ```php PHP theme={null}
  <?php
  $ch = curl_init();

  curl_setopt($ch, CURLOPT_URL, 'https://dhmad.tn/api/v1/escrows');
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      'Authorization: Bearer sk_live_abc123...',
      'Content-Type: application/json'
  ]);

  $response = curl_exec($ch);
  curl_close($ch);
  ?>
  ```
</CodeGroup>

## 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](/guides/sandbox) (`https://sandbox.dhmad.tn/api`)

<Warning>
  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`.
</Warning>

## Account Association

<Warning>
  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](https://developer.dhmad.tn/dashboard).
</Warning>

## Security Best Practices

<CardGroup cols={2}>
  <Card title="Store Securely" icon="lock">
    Never commit API keys to version control. Use environment variables or secret management services.
  </Card>

  <Card title="Rotate Regularly" icon="refresh">
    Regenerate your API keys periodically for better security.
  </Card>

  <Card title="Use Different Keys" icon="key">
    Use separate API keys for development, staging, and production environments.
  </Card>

  <Card title="Monitor Usage" icon="chart-line">
    Regularly check your API key usage in the dashboard for any suspicious activity.
  </Card>
</CardGroup>

## Error Responses

### 401 Unauthorized

If your API key is missing or invalid, you'll receive a 401 error:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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](https://developer.dhmad.tn/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

<Info>
  The default rate limit applies per IP address. If you need higher limits, contact [support@dhmad.tn](mailto:support@dhmad.tn)
</Info>

## Testing Your Authentication

You can test your API key by making a simple request to the balance endpoint:

```bash theme={null}
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

***

<Warning>
  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.
</Warning>