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

# Authentication

> Learn how to authenticate with the Thunder API

## API Keys

API keys are used to identify your project and authenticate requests. Each key is scoped to a single project.

### Using Your API Key

Include your API key in the `x-api-key` header with every request:

```bash theme={null}
curl https://api.usethunder.com/v1/ingest \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '...'
```

### Key Format

API keys follow this format:

```
tk_live_abc123def456...
```

* `tk_` - Thunder key prefix
* `live_` or `test_` - Environment indicator
* Random alphanumeric string

<Warning>
  Never expose your API keys in client-side code or public repositories. API keys should only be used in server-side applications.
</Warning>

## Error Responses

### Missing API Key

If you forget to include the `x-api-key` header:

```json theme={null}
{
  "success": false,
  "error": {
    "code": "MISSING_API_KEY",
    "message": "x-api-key header is required"
  }
}
```

**Status code:** `401 Unauthorized`

### Invalid API Key

If your API key is incorrect or has been revoked:

```json theme={null}
{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid or inactive API key"
  }
}
```

**Status code:** `401 Unauthorized`

## Rate Limiting

The API enforces rate limits to ensure fair usage:

| Limit                           | Value  |
| ------------------------------- | ------ |
| Requests per second             | 1,000  |
| Max messages per ingest request | 10,000 |

When you exceed the rate limit, you'll receive a `429 Too Many Requests` response. Implement exponential backoff in your integration to handle rate limits gracefully.

## Security Best Practices

<AccordionGroup>
  <Accordion title="Store keys securely">
    Use environment variables or a secrets manager. Never hardcode API keys in your source code.
  </Accordion>

  <Accordion title="Use server-side only">
    Make API calls from your backend, not from browsers or mobile apps where keys could be extracted.
  </Accordion>

  <Accordion title="Rotate keys periodically">
    Create new keys and revoke old ones on a regular schedule. This limits the impact if a key is compromised.
  </Accordion>

  <Accordion title="Use separate keys per environment">
    Use different API keys for development, staging, and production to maintain isolation.
  </Accordion>
</AccordionGroup>