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

# Authenticate with the Braintest API

> Learn how to obtain your Braintest API key from the organizer panel and send it in the API-KEY header on every request.

Every request to the Braintest API must include a valid API key in the `API-KEY` header. This page explains how to obtain your key, how to send it, and how to handle authentication errors.

## Obtaining your key

1. Log in to the Braintest organizer panel.
2. Navigate to **Settings > API Keys**.
3. Generate a new key. Copy it and store it securely. Braintest does not show it again.

<Warning>
  Treat your API key like a password. Do not commit it to version control, expose it in client-side code, or share it in public repositories.
</Warning>

## Sending the key

Include the `API-KEY` header on every request, regardless of HTTP method.

```bash theme={"dark"}
curl -X GET "https://braintest.ir/api/v2/record/" \
  -H "API-KEY: YOUR_API_KEY"
```

## Authentication errors

The API returns specific HTTP status codes and envelope messages for authentication problems.

| Status | Meaning                     | What to do                                                                                                 |
| ------ | --------------------------- | ---------------------------------------------------------------------------------------------------------- |
| 401    | Missing or invalid API key  | Check that the `API-KEY` header is present and the value matches the key from the organizer panel.         |
| 403    | Valid key but access denied | The key may be revoked, expired, or your IP address is not on the allowlist. Contact your organizer admin. |

Example 401 response:

```json theme={"dark"}
{
  "data": null,
  "successful": false,
  "messages": ["Invalid API key provided."]
}
```

## Key lifecycle

* **Expiration**: Keys can be set to expire after a specific date. Expired keys return 403.
* **Revocation**: An organizer admin can revoke a key at any time. Revoked keys return 403.
* **IP allowlist**: Keys can be restricted to specific IP addresses. Requests from other IPs return 403.

<Tip>
  Rotate your API keys periodically. Generate a new key in the organizer panel, update your integration, and revoke the old key.
</Tip>

## Security best practices

* Store the key in environment variables or a secrets manager, never in source code.
* Do not expose the `API-KEY` header in browser-side JavaScript or mobile app code. Route requests through your backend.
* Use HTTPS for all API calls. The Braintest API rejects plain HTTP requests.