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

# Authentication

> Authenticate with the Superlines REST API.

The Superlines REST API uses **Bearer token** authentication. Include your token in the `Authorization` header of every request.

## Supported token types

| Token type             | Format        | Use case                                 |
| ---------------------- | ------------- | ---------------------------------------- |
| **API Key**            | `sl_live_...` | Server-side integrations, scripts, CI/CD |
| **OAuth Access Token** | JWT           | MCP clients using OAuth flow             |
| **Firebase ID Token**  | JWT           | Internal/browser-based access            |

## Getting your API key

<Steps>
  <Step title="Go to Organization Settings → API Keys" />

  <Step title="Click Generate API Key">
    A key is created with the format `sl_live_...`
  </Step>

  <Step title="Copy and store it securely">
    Keys are shown only once at creation.
  </Step>
</Steps>

## Using your API key

Include it in the `Authorization` header. The API supports both **GET** and **POST** requests.

```bash theme={null}
curl -X POST https://api.superlines.io \
  -H "Authorization: Bearer sl_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"endpoint": "metrics", "metrics": ["brand_visibility"]}'
```

Or in code:

<Tabs>
  <Tab title="JavaScript">
    ```javascript theme={null}
    const response = await fetch('https://api.superlines.io', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer sl_live_YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        endpoint: 'metrics',
        metrics: ['brand_visibility', 'citation_rate'],
        brands: ['My Brand'],
        startDate: '2025-01-01',
        endDate: '2025-01-31'
      })
    });
    const data = await response.json();
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import requests

    response = requests.post(
        'https://api.superlines.io',
        headers={
            'Authorization': 'Bearer sl_live_YOUR_API_KEY',
            'Content-Type': 'application/json'
        },
        json={
            'endpoint': 'metrics',
            'metrics': ['brand_visibility', 'citation_rate'],
            'brands': ['My Brand'],
            'startDate': '2025-01-01',
            'endDate': '2025-01-31'
        }
    )
    data = response.json()
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST https://api.superlines.io \
      -H 'Authorization: Bearer sl_live_YOUR_API_KEY' \
      -H 'Content-Type: application/json' \
      -d '{
        "endpoint": "metrics",
        "metrics": ["brand_visibility", "citation_rate"],
        "brands": ["My Brand"],
        "startDate": "2025-01-01",
        "endDate": "2025-01-31"
      }'
    ```
  </Tab>
</Tabs>

## Error responses

| Status                  | Meaning                                         |
| ----------------------- | ----------------------------------------------- |
| `401 Unauthorized`      | Missing or invalid token                        |
| `403 Forbidden`         | Token doesn't have permission for this resource |
| `429 Too Many Requests` | Rate limit exceeded — slow down                 |

## Security best practices

<Warning>
  * **Never expose API keys in client-side code** — they belong on your server
  * **Use environment variables** to store keys
  * **Rotate keys regularly** and revoke compromised ones immediately
  * **One key per integration** — makes it easy to revoke individually
</Warning>