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

# Authentication

> API authentication and rate limits for Enter Theatre

## Overview

The Enter Theatre API supports two access levels:

| Access Level    | Rate Limit          | Use Case                |
| --------------- | ------------------- | ----------------------- |
| Public (no key) | 100 requests/day    | Testing, small projects |
| API Key         | 10,000 requests/day | Production apps         |

All `GET` endpoints are publicly accessible. Write operations (`POST`, `PUT`, `DELETE`) require Supabase authentication.

## Rate Limits

### Without API Key

Anonymous requests are rate-limited by IP address:

* **100 requests per day**
* Resets at midnight UTC

```bash theme={null}
curl https://entertheatre.com/api/shows
```

### With API Key

Authenticated requests using an API key get higher limits:

* **10,000 requests per day** (default)
* Resets at midnight UTC

```bash theme={null}
curl https://entertheatre.com/api/shows \
  -H "Authorization: Bearer et_your_api_key_here"
```

### Rate Limit Headers

Every response includes rate limit information:

| Header                  | Description                      |
| ----------------------- | -------------------------------- |
| `X-RateLimit-Limit`     | Maximum requests allowed         |
| `X-RateLimit-Remaining` | Requests remaining in window     |
| `X-RateLimit-Reset`     | Unix timestamp when limit resets |

### Rate Limit Exceeded

When you exceed the rate limit, you'll receive a `429` response:

```json theme={null}
{
  "error": "Rate limit exceeded",
  "message": "Public API limit of 100 requests per day exceeded. Sign up for an API key for higher limits.",
  "limit": 100,
  "reset": 1701388800
}
```

## Getting an API Key

<Steps>
  <Step title="Create an account">
    Sign up at [entertheatre.com/signup](https://entertheatre.com/signup)
  </Step>

  <Step title="Go to Developer Dashboard">
    Visit [entertheatre.com/dashboard/api-keys](https://entertheatre.com/dashboard/api-keys)
  </Step>

  <Step title="Create a new key">
    Click "Create New Key" and give it a descriptive name
  </Step>

  <Step title="Copy your key">
    Copy your API key immediately - you won't be able to see it again!
  </Step>
</Steps>

## Using Your API Key

Include your API key in the `Authorization` header:

<CodeGroup>
  ```bash cURL theme={null}
  curl https://entertheatre.com/api/shows \
    -H "Authorization: Bearer et_abc123..."
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://entertheatre.com/api/shows', {
    headers: {
      'Authorization': 'Bearer et_abc123...'
    }
  });
  const shows = await response.json();
  ```

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

  response = requests.get(
      'https://entertheatre.com/api/shows',
      headers={'Authorization': 'Bearer et_abc123...'}
  )
  shows = response.json()
  ```
</CodeGroup>

## Invalid API Key

If you provide an invalid or revoked API key, you'll receive a `401` response:

```json theme={null}
{
  "error": "Invalid API key",
  "message": "The provided API key is invalid or has been revoked."
}
```

## Write Operations

For create, update, and delete operations, you need to be authenticated via Supabase session (not API key). This is intended for the admin dashboard, not external API consumers.

## Best Practices

<CardGroup cols={2}>
  <Card title="Keep keys secret" icon="lock">
    Never commit API keys to version control or expose them in client-side code.
  </Card>

  <Card title="Use environment variables" icon="gear">
    Store your API key in environment variables like `ENTER_THEATRE_API_KEY`.
  </Card>

  <Card title="Monitor usage" icon="chart-line">
    Check your usage in the dashboard to avoid hitting rate limits.
  </Card>

  <Card title="Rotate keys" icon="rotate">
    If a key is compromised, revoke it immediately and create a new one.
  </Card>
</CardGroup>