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

# Authentication

> Authenticate with an API key and project context

## Overview

All MentionLab REST API requests require an API key sent in the `x-api-key` header. Your API key is scoped to a single organization and can access all projects within that organization.

<Info>
  Project-scoped API keys are on the roadmap.
</Info>

## Get Your API Key

You can retrieve your API key from the dashboard:

<Steps>
  <Step title="Sign in to MentionLab">
    Go to [app.mentionlab.io](https://app.mentionlab.io) and sign in to your account.
  </Step>

  <Step title="Open API Keys">
    Use the organization switcher in the top bar, choose **Organization settings**, then
    **Developer settings → API Keys** in the sidebar.
  </Step>

  <Step title="Create the key">
    Click **Create API Key** and set a **Name**, a **Permission** (`Read only` or `Read & Write`)
    and an optional **Expiration Date** — leave it empty for a key that never expires.
  </Step>

  <Step title="Copy and store securely">
    Copy your API key immediately. For security reasons, you will not be able to see it again.
  </Step>
</Steps>

<Note>
  Only organization Administrators can create or delete keys. Editors can see the list.
</Note>

### Permissions

| Permission       | What the key can do                            |
| ---------------- | ---------------------------------------------- |
| **Read only**    | Read organizations, projects and analytics     |
| **Read & Write** | The above, plus create and update project data |

<Warning>
  `Read & Write` is not full access. It cannot delete projects, manage members, or change
  organization settings and billing — those actions return 403 regardless of the key.
</Warning>

<Warning>
  Your API key is only shown once when generated. Store it securely in a password manager or environment variable. If you lose it, you will need to generate a new one.
</Warning>

## API Key Format

MentionLab API keys use the following format:

```
ml_live_abc123xyz789def456...
```

API keys always start with `ml_live_` for production keys.

## Using Your API Key

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

```bash theme={null}
x-api-key: ml_live_abc123xyz789def456...
```

### Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.mentionlab.io/api/v1/projects" \
    -H "x-api-key: ml_live_abc123xyz789..."
  ```

  ```javascript Node.js theme={null}
  const apiKey = process.env.MENTIONLAB_API_KEY;

  const response = await fetch('https://api.mentionlab.io/api/v1/projects', {
    headers: {
      'x-api-key': apiKey
    }
  });
  ```

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

  api_key = os.environ['MENTIONLAB_API_KEY']

  response = requests.get(
      'https://api.mentionlab.io/api/v1/projects',
      headers={
          'x-api-key': api_key
      }
  )
  ```
</CodeGroup>

<Tip>
  `GET /api/v1/projects` needs no project header, so it's the natural first call to verify a key
  and discover your project IDs.
</Tip>

## Environment Variables

We recommend storing your API key in environment variables:

<Tabs>
  <Tab title="Unix/Linux/macOS">
    ```bash theme={null}
    export MENTIONLAB_API_KEY="your-api-key-here"
    ```
  </Tab>

  <Tab title=".env file">
    ```bash theme={null}
    # .env file (add to .gitignore!)
    MENTIONLAB_API_KEY=your-api-key-here
    MENTIONLAB_PROJECT_ID=your-default-project-id
    ```
  </Tab>
</Tabs>

<Check>
  Always add `.env` files to your `.gitignore` to prevent accidentally committing secrets to version control.
</Check>

## Required Headers

| Header         | Required              | Description                                |
| -------------- | --------------------- | ------------------------------------------ |
| `x-api-key`    | Always                | Your API key (format: `ml_live_...`)       |
| `x-project-id` | For project endpoints | Project UUID for project-scoped operations |

## Example Request

Most list endpoints are `POST`, with filters and paging in the body:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.mentionlab.io/api/queries/list" \
    -H "x-api-key: ml_live_abc123xyz789..." \
    -H "x-project-id: fedcba98-7654-3210-fedc-ba9876543210" \
    -H "Content-Type: application/json" \
    -d '{"page": 1, "limit": 50}'
  ```
</CodeGroup>

## Project Context

Project-specific endpoints require the `x-project-id` header so the API knows which project to operate on. You can store a default project ID in your environment if most requests target a single project.

<Note>
  A missing or invalid context header returns **403**, not 400 — for example
  `Missing project id context` or `Project does not belong to specified organisation`.
</Note>

## Invalid keys

| Situation                                | Response                                                      |
| ---------------------------------------- | ------------------------------------------------------------- |
| No `x-api-key` header                    | `401 Missing API key header`                                  |
| Unrecognised key                         | `401 Invalid API key`                                         |
| Key past its expiration date             | `401 API key has expired`                                     |
| Key lacks the permission the route needs | `403` naming the missing permission                           |
| Endpoint not available to API keys       | `403 API key authentication is not allowed for this endpoint` |

## Rate Limits

The MentionLab API implements rate limiting to ensure fair usage and maintain service stability for all users. Understanding these limits helps you design efficient integrations that avoid throttling.

### Default Rate Limits

All accounts share the same default rate limits:

| Metric              | Limit  |
| ------------------- | ------ |
| Requests per Second | 10     |
| Requests per Minute | 300    |
| Requests per Hour   | 10,000 |

<Note>
  If you have a custom agreement with MentionLab, your rate limits may differ from the defaults listed here. Please refer to your agreement documentation for your specific limits.
</Note>

### Rate Limit Headers

Every API response includes headers to help you track your usage:

| Header                  | Description                                             |
| ----------------------- | ------------------------------------------------------- |
| `X-RateLimit-Limit`     | Maximum requests allowed in the current window          |
| `X-RateLimit-Remaining` | Requests remaining in the current window                |
| `X-RateLimit-Reset`     | Unix timestamp when the rate limit resets               |
| `Retry-After`           | Seconds to wait before retrying (only on 429 responses) |

### Handling Rate Limits

When you exceed the rate limit, the API returns a `429 Too Many Requests` response:

<CodeGroup>
  ```json Response theme={null}
  {
    "statusCode": 429,
    "message": "Too many requests. Please retry after 30 seconds.",
    "error": "Too Many Requests"
  }
  ```

  ```bash Headers theme={null}
  HTTP/1.1 429 Too Many Requests
  X-RateLimit-Limit: 300
  X-RateLimit-Remaining: 0
  X-RateLimit-Reset: 1701234567
  Retry-After: 30
  ```
</CodeGroup>

### Error Codes

| Code  | Description                     | Action                                   |
| ----- | ------------------------------- | ---------------------------------------- |
| `429` | Rate limit exceeded             | Wait for `Retry-After` seconds and retry |
| `503` | Service temporarily unavailable | Wait 30 seconds and retry with backoff   |

## Next Steps

<CardGroup cols={2}>
  <Card title="Context Headers" icon="list" href="/rest-api/headers">
    See all header requirements and examples.
  </Card>

  <Card title="REST API Getting Started" icon="code" href="/rest-api/getting-started">
    Review base URL, JSON requirements, and rate limits.
  </Card>
</CardGroup>