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

# Authentication

> Authenticate API requests using Bearer token API keys.

## Bearer Token Authentication

All API requests require a Bearer token in the `Authorization` header. API keys use the `imk_` prefix.

```bash theme={null}
curl https://getimmutable.dev/api/v1/events \
  -H "Authorization: Bearer imk_a1b2c3d4e5f6g7h8i9j0..."
```

## Key Security

* Keys are **bcrypt hashed** before storage. Immutable never stores your raw key.
* A **20-character prefix** is stored for key lookup and identification in the dashboard.
* Keys are shown **only once** at creation. If you lose a key, revoke it and generate a new one.

<Warning>
  Never expose your API key in client-side code, public repositories, or browser-accessible JavaScript. API keys should only be used in server-side environments. See the [Next.js guide](/guides/nextjs) for safe patterns.
</Warning>

## Key Management

Each workspace can have multiple active API keys. The limit depends on your plan:

| Plan       | API Key Limit |
| ---------- | ------------- |
| Free       | 2             |
| Starter    | 5             |
| Pro        | 20            |
| Enterprise | Unlimited     |

Manage keys from **Settings > API Keys** in the dashboard:

* Create new keys with a descriptive label
* View the prefix of existing keys for identification
* Revoke keys immediately (takes effect instantly)

## Environments

Use separate API keys for development and production. Each key is scoped to a single workspace, so you can create a dedicated test workspace with its own keys.

## Rate Limits

API requests are rate limited per workspace:

| Plan       | Requests / Minute |
| ---------- | ----------------- |
| Free       | 60                |
| Starter    | 300               |
| Pro        | 1,000             |
| Enterprise | Custom            |

When rate limited, the API returns `429 Too Many Requests` with a `Retry-After` header indicating when to retry.

## Error Responses

### 401 Unauthenticated

Missing or invalid API key:

```json theme={null}
{
  "error": "unauthenticated",
  "message": "Invalid or missing API key."
}
```

### 403 Forbidden

IP not in allowlist or insufficient permissions:

```json theme={null}
{
  "error": "forbidden",
  "message": "Your IP address is not in the workspace allowlist."
}
```

See [IP Allowlisting](/security/ip-allowlisting) for restricting API access by IP address.