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

# Authentication

> How to authenticate with the Roulette API

## API Keys

All API requests require a Bearer token in the `Authorization` header:

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

API keys start with `mk_` and are tied to your user account.

## Getting your API Key

<Steps>
  <Step title="Access Settings">
    Log into [Roulette](https://www.useroulette.com/home), click your team name in the sidebar, then go to **Settings** → **API Keys**.
  </Step>

  <Step title="Create a Key">
    Click **Create API Key** and give it a descriptive name (e.g., "Zapier", "Internal Scripts").
  </Step>

  <Step title="Copy and Store">
    Copy the key immediately - you won't see it again.

    <Warning>
      Never commit API keys to version control. Use environment variables.
    </Warning>
  </Step>
</Steps>

## Example Requests

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://www.useroulette.com/api/v1/companies" \
    -H "Authorization: Bearer mk_abc123..."
  ```

  ```javascript JavaScript theme={null}
  const API_KEY = process.env.ROULETTE_API_KEY;

  const response = await fetch('https://www.useroulette.com/api/v1/companies', {
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    }
  });
  ```

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

  API_KEY = os.environ['ROULETTE_API_KEY']

  response = requests.get(
      'https://www.useroulette.com/api/v1/companies',
      headers={'Authorization': f'Bearer {API_KEY}'}
  )
  ```
</CodeGroup>

## Error Responses

### 401 Unauthorized

```json theme={null}
{
  "success": false,
  "error": "Invalid or expired API key"
}
```

| Cause          | Solution                              |
| -------------- | ------------------------------------- |
| Invalid key    | Check for typos or generate a new key |
| Missing header | Add `Authorization: Bearer YOUR_KEY`  |
| Deleted key    | Create a new API key in settings      |

### 403 Forbidden

```json theme={null}
{
  "success": false,
  "error": "Access denied to this resource"
}
```

Your API key only has access to teams your user account belongs to. Request access from the team owner if needed.

## Best Practices

<AccordionGroup>
  <Accordion title="Use Environment Variables">
    ```bash theme={null}
    # .env (never commit this file)
    ROULETTE_API_KEY=mk_abc123...
    ```

    ```javascript theme={null}
    const apiKey = process.env.ROULETTE_API_KEY;
    ```
  </Accordion>

  <Accordion title="Separate Keys per Environment">
    Create different keys for development, staging, and production. This lets you rotate keys independently and track usage.
  </Accordion>

  <Accordion title="Rotate Keys Periodically">
    Delete old keys and create new ones regularly. You can have multiple active keys for zero-downtime rotation.
  </Accordion>
</AccordionGroup>

## Rate Limits

| Limit               | Value |
| ------------------- | ----- |
| Requests per minute | 1,000 |
| Requests per second | 100   |

When rate limited, you'll receive `429 Too Many Requests`:

```json theme={null}
{
  "success": false,
  "error": "Rate limit exceeded"
}
```

<Tip>
  Implement exponential backoff to handle rate limits gracefully.
</Tip>

## Permissions

Your API key inherits your user permissions:

* Access is limited to teams you're a member of
* Row Level Security (RLS) applies to all requests
* You can only see companies based on your team's visibility settings