Skip to content

Authentication and rate limits

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

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)

Section titled “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). 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.

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

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

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

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

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

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:

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

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

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)
{
"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.

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