API keys and rate limits

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.

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

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. 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

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 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.

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.

Connectors have their own limit per team and provider, to protect the provider’s quota; see Connectors.

Command reference: api-key create, api-key list, api-key rotate, api-key revoke and api-key limits.