---
title: "API keys and rate limits"
description: "Team API keys with scopes, an optional project, expiry, rotation and instant revocation, and the per-minute limit that comes from your plan data, with 429, Retry-After and the RateLimit headers."
---

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

# API keys and rate limits

An API key is a long-lived bearer credential for a service that is not a person: a CI job, a deploy script, your own backend. Keys belong to the team, not to a person's session.

## Create, list, rotate, revoke

```sh
overlane api-key create --label ci-nightly --scope read
overlane api-key create --label deploy --scope write --project proj-1 --ttl-days 30 --rate-limit 120
overlane api-key list
overlane api-key rotate key_0123456789abcdef
overlane api-key revoke key_0123456789abcdef --force
```

The secret starts with `ovl_k_` and is shown once, at creation and at rotation. Only a hash is stored, so `overlane api-key list` shows the prefix, never the secret. Store the secret like any other credential.

| Setting | Meaning |
| --- | --- |
| Scope | `read` allows read routes only. `write` includes read. A read key that calls a write route gets `403 insufficient_scope`. |
| Project | Optional. A key limited to one project is refused on every other project's paths. |
| Lifetime | 90 days by default, one year at most. An expired key gets `401 token_expired`. |
| Cap | Optional calls per minute for this key, under the plan limit. |

A key acts as an agent for the member who made it and never holds more than that member: a key made by a member without the right to change policy cannot change policy. If that member leaves the team, the key is revoked on its next use.

**Revoking is immediate.** Every call reads the database, so a revoked key fails on the very next request with `401 token_revoked`. Rotating issues a new key with the same label, scopes, project and cap, and revokes the old key in the same step.

## Autonomy

Creating, rotating or revoking a key is in the `secrets` [autonomy class](/autonomy/). A person passes. An agent needs an approval from an independent agent (or a person): the refusal names the class and the subject to approve, an independent principal answers with evidence and a reason, and the agent retries with the approval ID in `OVERLANE_APPROVAL` (the CLI) or the `x-overlane-approval` header (the API).

## Rate limits

The limit comes from the plan data file, the same one the pricing page and the billing service read. It is pooled across all of a team's keys.

| Plan | Calls a minute |
| --- | --- |
| Free | 60 |
| Pro, Team, Business and Enterprise | 600 |

```js run
const policy = RateLimitPolicy.parse({ tenantId: "t1", source: "plan", plan: "free", limit: 60, windowSeconds: 60 });
assert.equal(policy.limit, 60);
assert.equal(RATE_LIMIT_HEADERS.retryAfter, "Retry-After");
```

A call over the limit gets:

- status `429` and the error shape from [REST API](/developers/rest-api/) with `retryable: true`;
- `Retry-After`, the seconds until the minute ends;
- `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` on every answer, so a client can slow down before it is refused.

```sh
overlane api-key limits
```

The limit applies to API keys. People signed in to the CLI or the web app and agent tokens are not counted against the keys' pool; they keep the MCP request limit and the abuse controls described under [Plans](/billing/plans/).

Connectors have their own limit per team and provider, to protect the provider's quota; see [Connectors](/developers/connectors/).

Command reference: [api-key create](/cli/api-key-create/), [api-key list](/cli/api-key-list/), [api-key rotate](/cli/api-key-rotate/), [api-key revoke](/cli/api-key-revoke/) and [api-key limits](/cli/api-key-limits/).

Source: https://docs.overlane.app/developers/api-keys-and-limits/index.mdx