---
title: "Authentication and rate limits"
description: "Bearer API keys and scopes, per-key rate limits, the daily page quota for scraping and crawling, and request IDs."
canonical_url: "https://developers.rankability.com/guides/authentication"
section: "Get started"
last_updated: 2026-11-14
---

# Authentication and rate limits

Bearer API keys and scopes, per-key rate limits, the daily page quota for scraping and crawling, and request IDs.

## Authentication

The Agent API uses **Bearer token authentication** with org-scoped API keys. Keys are prefixed with `rk_live_` and validated via SHA-256 hash lookup.

```
Authorization: Bearer rk_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ012345678901
```

API keys are managed by organization admins through the key management endpoints (which use Clerk session auth, not Bearer tokens), or through the **Settings > API keys** tab in the Rankability UI.

### Sign in from a terminal or CI (device authorization)

A script can get its own credential with one browser approval, without anyone copying a key. Rankability supports the OAuth 2.0 device authorization grant ([RFC 8628](https://www.rfc-editor.org/rfc/rfc8628)). The script prints a short code and a link; you open the link while signed in to Rankability, check the code, and approve. The script then receives an OAuth access token (`oat_...`) that works as `Authorization: Bearer` on every endpoint in this guide, limited to the scopes you approved and to the organization you had active.

1. **Register the client once** with the device grant declared. A device client needs no redirect URI.

   ```bash
   curl -sS -X POST https://app.rankability.com/oauth/register \
     -H "Content-Type: application/json" \
     -d '{"client_name":"My CI job","grant_types":["urn:ietf:params:oauth:grant-type:device_code","refresh_token"],"token_endpoint_auth_method":"none"}'
   # => { "client_id": "mcp_...", "grant_types": [...], ... }
   ```

   Clients that identify themselves with a Client ID Metadata Document URL instead list the same `grant_types` in that document.

2. **Start the request** and show the person the code and link.

   ```bash
   curl -sS -X POST https://app.rankability.com/oauth/device_authorization \
     --data-urlencode "client_id=mcp_..." \
     --data-urlencode "scope=reporter:read clients:read"
   # => { "device_code": "odc_...", "user_code": "BCDF-GHJK",
   #      "verification_uri": "https://app.rankability.com/oauth/device",
   #      "verification_uri_complete": "https://app.rankability.com/oauth/device?user_code=BCDF-GHJK",
   #      "expires_in": 600, "interval": 5 }
   ```

3. **Approve in the browser.** The page shows the app's name, the permissions it asks for and the code. Approve only if you started the request yourself and the code matches.

4. **Poll for the token** every `interval` seconds until it is issued.

   ```bash
   curl -sS -X POST https://app.rankability.com/oauth/token \
     --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:device_code" \
     --data-urlencode "device_code=odc_..." \
     --data-urlencode "client_id=mcp_..."
   # => { "access_token": "oat_...", "token_type": "Bearer", "expires_in": 3600,
   #      "refresh_token": "ort_...", "scope": "reporter:read clients:read" }
   ```

   Until then the response is `400` with one of these errors:

   | `error` | Meaning |
   |---|---|
   | `authorization_pending` | Not approved yet. Keep polling. |
   | `slow_down` | Polling too often. Add 5 seconds to your interval (the response includes the new `interval`). |
   | `access_denied` | The person chose Deny. Stop. |
   | `expired_token` | The 10-minute window passed. Start again. |
   | `invalid_grant` | Unknown or already-used device code, or a different client. Stop. |

5. **Call the API** with the access token, for example `GET /usage` (needs `reporter:read` or any other read scope that endpoint accepts). Refresh it with `grant_type=refresh_token` before the hour is up, exactly as for the MCP OAuth flow.

Each device code works once. Device codes expire after 10 minutes, and code lookups on the approval page are rate-limited. The connection appears under connected apps in Settings, where it can be disconnected. API keys are still created only in **Settings > API keys**; there is no endpoint that creates a key from another credential.

### Plan requirements

API access is included on **every paid plan** (Core, Team, and Agency) at no add-on cost. Every full-platform paid plan gets the same request-rate limit; see [Rate limits](#rate-limits) for the per-plan table. An active subscription is required — if your org does not have an active subscription, both key creation and job creation return a `403` error.

### Scopes

Each key has one or more scopes that control what operations it can perform:

| Scope | Description |
|---|---|
| `copywriter:run` | Create jobs, approve briefs, replace drafts, mark/unmark Done, delete jobs |
| `copywriter:read` | Poll status, retrieve artifacts, list jobs, export content |
| `reporter:read` | List projects, get SPI scores, results, trends, summary |
| `reporter:run` | Trigger new Reporter scans |
| `reporter:write` | Create, update, delete Reporter projects |
| `clients:read` | List clients, get client details |
| `clients:write` | Create, update, delete clients |
| `kb:read` | Fetch all published KB articles and FAQ content |
| `optimize:run` | Score pages against SERP competitors via the Optimize endpoint |
| `routines:read` | Read all Automate settings and technical audit history; no changes or runs |
| `routines:write` | Create, enable, pause and change Automate workflows; authorize their recurring usage |
| `publishing:read` | Read credential-free connections and delivery receipts without publishing, retrying, or validating |
| `publishing:write` | Request a confirmed, idempotent draft delivery; never authorizes live publishing |
| `serena:ask` | Ask Serena client-scoped questions through the read-only consultation endpoint |

### Rate limits

All agent endpoints are rate-limited per API key (or per OAuth credential for MCP connections) over a sliding 60-second window. MCP tool calls count against the same limit as direct API calls. The limit depends on the product and plan the organization is on:

<!-- api-rate-limits:start -->

| Product | Plan | Requests per minute, per key | Requests per day |
| --- | --- | --- | --- |
| Rankability | Starter (including trials), and earlier Starter and Core Lite plans | 60 | No daily cap |
| Rankability | Growth (including trials), and earlier Core and Growth plans | 120 | No daily cap |
| Rankability | Pro (including trials), and earlier Team, Scale and Agency plans | 240 | No daily cap |
| Rankability | Free | 30 | No daily cap |
| Copywriter plans | Core | 30 | No daily cap |
| Copywriter plans | Scale | 60 | No daily cap |
| Copywriter plans | High-volume | 120 | No daily cap |
| SEO Researcher | Free sample and Starter | 60 | No daily cap |
| SEO Researcher | Pro | 120 | No daily cap |
| SEO Researcher | Agency | 240 | No daily cap |
| SEO Researcher | Scale | 500 | No daily cap |

<!-- api-rate-limits:end -->

There is no daily request cap today. Your `X-RateLimit-Limit` header is authoritative.

Rate limit headers are included in every response. `Retry-After` is sent on every `429` that has a known retry time: `rate_limit_exceeded`, `usage_limit_reached`, `capacity_reached` and `concurrency_limit_reached`.

| Header | Description |
|---|---|
| `X-RateLimit-Limit` | Maximum requests per minute for this key |
| `X-RateLimit-Remaining` | Remaining requests in current window |
| `X-RateLimit-Reset` | Seconds until the window resets |
| `Retry-After` | Seconds to wait before retrying |

### Daily page quota (scrape / crawl)

Separately from the request rate limit, the page-fetching endpoints (`POST /scrape` and `POST /crawl`) enforce a **per-org daily page-volume quota** — a safety cap on how many pages a single org can fetch in a rolling UTC day. When the cap is reached, requests are rejected with `429 quota_exceeded` until the UTC day rolls over.

Both endpoints return quota headers on every response — including the `429 quota_exceeded` rejection — so you can self-throttle before you hit the hard cap:

| Header | Description |
|---|---|
| `X-Quota-Limit` | Daily page quota (pages per UTC day) |
| `X-Quota-Used` | Pages consumed so far in the current UTC day |
| `X-Quota-Remaining` | Pages remaining before the quota is exhausted |

Counts reset at the start of each UTC day. The numbers reflect usage on the instance that served the request (the quota is enforced per instance), so on a horizontally-scaled deployment the per-request figure is a lower bound on org-wide usage.

To check your allowance **without** making a billable scrape/crawl call, use the read-only usage endpoint:

```
GET /crawler/usage          (scope: scrape:run or crawl:run)
```

```json
{
  "daily_page_quota": {
    "limit": 50000,
    "used": 1280,
    "remaining": 48720,
    "window_date": "2026-06-21",
    "scope": "this_instance"
  }
}
```

The `limit` is resolved from your plan tier (the same tier-derived resolution that backs the hard cap), so higher-paying plans see a larger allowance. The same `X-Quota-*` headers are also set on this response.

### Request tracking

Every response includes an `X-Request-Id` header for tracing and debugging.
