# Authentication

> Authenticate requests, handle rate limits and errors.

Section: Getting Started
Source: https://coincircuit.io/docs/guides/authentication/
Interactive version: https://coincircuit.io/api-reference?tab=guides&guide=authentication

Authenticate every request by sending your API key in the `x-api-key` header.

```http
x-api-key: your_api_key_here
```

## API keys
Generate keys in the dashboard under **Developer > API Keys**. Use test keys against the sandbox base URL and live keys against production. Treat keys like passwords and keep them out of public repositories.

## Rate limiting
The API allows **100 requests per minute**. Exceeding the limit returns a `429 Too Many Requests` response.

## Pagination
List endpoints accept `page` (default 1) and `size` (default 10, max 100) query parameters. Paginated responses include a `meta` object:

```json
"meta": { "page": 1, "size": 10, "total": 42, "totalPages": 5 }
```

## Error handling
The API uses standard HTTP status codes to signal success or failure.

| Status | Meaning |
| :--- | :--- |
| 400 | Invalid or malformed request |
| 401 | Invalid or missing authentication |
| 404 | Resource not found |
| 409 | Resource conflict |
| 503 | Service unavailable |

Error responses share one shape:

```json
{
  "success": false,
  "timestamp": "2026-01-23T23:33:55.685Z",
  "path": "/api/v1/payments",
  "method": "POST",
  "error": "Unauthorized",
  "message": "Unauthorized"
}
```