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

# API keys

> Provision and manage the keys that authenticate REST API requests, and understand the plan and rate-limit rules that apply.

API keys authenticate requests to the [Mavel REST API](/api-reference/introduction).
Pass the key in an `X-API-Key` HTTP header on every request (a query-string
fallback exists, but never use it; see Security practices below). Keys are
project-scoped: each key is tied to a specific project (or to the organization,
with access to any of its projects) and cannot reach data outside that scope.

<Note>
  API access requires the **Growth plan or above**. On Starter and Pro, the API
  Keys page shows an upgrade prompt. See [Plans and billing](/account/plans).
</Note>

## Provisioning a key

Self-serve key creation in the dashboard is coming soon. In the meantime,
contact [support@newbest.ai](mailto:support@newbest.ai) to provision an API key
for your organization. If you are on Growth or Enterprise, you can also connect
through the [MCP server](/mcp/introduction) today without waiting for a key.

Once provisioned, you will receive the key value once: copy it immediately and
store it securely. Mavel stores only a hashed fingerprint; the raw key is not
recoverable after the creation response.

## Using a key

Pass the key in every API request using the `X-API-Key` header:

```
X-API-Key: your_key_here
```

Include the `project_id` query parameter (for GET endpoints) or in the request
body (for POST endpoints) to scope the request to the right project. The API
returns a `403` if the key's bound project does not match the requested
`project_id`.

## Rate limits

The API enforces a limit of **200 requests per minute per project**. Each
response includes rate-limit headers so you can track remaining headroom:

| Header                  | Meaning                                         |
| ----------------------- | ----------------------------------------------- |
| `X-RateLimit-Limit`     | Maximum requests per minute (200)               |
| `X-RateLimit-Remaining` | Requests left in the current window             |
| `X-RateLimit-Reset`     | Unix timestamp (seconds) when the window resets |

When the limit is exceeded, the API returns `429 Too Many Requests`. Back off
and retry after the `X-RateLimit-Reset` time.

## Revoking a key

Contact [support@newbest.ai](mailto:support@newbest.ai) to revoke a key. Revoked
keys are immediately rejected by the API. If a key may have been exposed,
request revocation right away. Do not wait.

## Security practices

* **Never put keys in URLs.** Query-string parameters appear in server logs,
  browser history, and referrer headers. Always use the `X-API-Key` header.
* **Never commit keys to source control.** Store them in environment variables
  or a secrets manager.
* **Never expose keys in client-side code.** All API calls must originate from
  your server or a trusted backend process, not from browser JavaScript.
* **Rotate promptly if a key leaks.** Request a revocation and a new key from
  support as soon as you suspect exposure.

## MCP as an alternative

If you need AI tools like Claude or Cursor to query your Mavel data, the
[MCP server](/mcp/introduction) is often simpler than raw API calls: it exposes
your visibility data as structured tools that AI clients can call directly,
without you writing API integration code. MCP access requires the same Growth
plan gate as the REST API.