Authentication | Rank Prompt API Docs

Search documentation /

Every request to the Public API authenticates with an opaque bearer token in the Authorization header. Browser CORS calls are blocked at the edge, so the API is server-to-server only.

The header

Shell JavaScript Python

curl https://api.rankprompt.com/v1/me \
-H "Authorization: Bearer rp_live_YOUR_KEY"

const res = await fetch('https://api.rankprompt.com/v1/me', {\nheaders: { Authorization: `Bearer ${process.env.RANKPROMPT_API_KEY}` },\n});\nconst me = await res.json();

import os, httpx

res = httpx.get(\n  "https://api.rankprompt.com/v1/me",\n  headers={"Authorization": f"Bearer {os.environ['RANKPROMPT_API_KEY']}"},\n  timeout=30,\n)\nres.raise_for_status()\nme = res.json()

Keys are prefixed with rp_live_ so they are easy to detect in logs and pull requests. We submit the prefix to GitHub secret scanning so leaks are caught automatically.

Scopes

Scopes are granular per resource. The implication hierarchy is: * ⊃ read:all / write:all ⊃ specific scopes; write:foo ⊃ read:foo.

Scope	Grants
`read:all`	Read access to every resource type.
`write:all`	Read + write access to every resource type.
`read:brands`	List and inspect brands.
`write:brands`	Create, update, and delete brands (implies read).
`read:reports`	List and inspect reports.
`write:reports`	Create, update, and delete reports (implies read).
`write:prompts`	Create, update, and delete prompts (implies read).
`read:jobs`	List and inspect jobs.
`write:jobs`	Create, update, and delete jobs (implies read).
`read:region-configs`	List and inspect region-configs.
`write:region-configs`	Create, update, and delete region-configs (implies read).
`read:scheduled`	List and inspect scheduled.
`write:scheduled`	Create, update, and delete scheduled (implies read).
`read:export-sections`	List and inspect export-sections.
`write:export-sections`	Create, update, and delete export-sections (implies read).
`read:citations`	List and inspect citations.
`read:audit`	List and inspect audit.
`read:webhooks`	List and inspect webhooks.
`write:webhooks`	Create, update, and delete webhooks (implies read).
`read:meta`	List and inspect meta.
`read:competitors`	List and inspect competitors.
`write:competitors`	Create, update, and delete competitors (implies read).
`read:content`	List and inspect content.
`write:content`	Create, update, and delete content (implies read).
`read:brand-audits`	List and inspect brand-audits.
`write:brand-audits`	Create, update, and delete brand-audits (implies read).
`read:tasks`	List and inspect tasks.
`write:tasks`	Create, update, and delete tasks (implies read).
`read:analytics`	List and inspect analytics.
`read:seo`	List and inspect seo.
`write:seo`	Create, update, and delete seo (implies read).

`read:meta` and `GET /v1/me`

GET /v1/me is the introspection endpoint that confirms your credentials work. It always returns user_id, auth_type and plan. The fields that describe what your key can do (key_prefix, scopes, allowed_brand_id) are only included when the key carries the read:meta scope.

When a request lands with insufficient scope you get back the insufficient_scope error from the error catalog: a 403 whose details carry both the missing scope (required_scope) and the scopes your key actually has (key_scopes):

{
  "error": {
    "code": "insufficient_scope",
    "message": "This endpoint requires the 'write:brands' scope",
    "details": {
      "required_scope": "write:brands",
      "key_scopes": ["read:brands"]
    }
  },
  "request_id": "01HZK3..."
}

Brand restriction

Optionally bind a key to a single brand at creation time (allowed_brand_id). The API will then refuse any request whose target brand does not match, even if the calling key carries write:all. This lets you issue per-brand keys to clients without having to spin up a new Rank Prompt workspace.

A request that crosses the boundary fails with brand_not_authorized (403).

Lifecycle: create, rotate, revoke

Manage keys from the Developers page inside your workspace. Common operations:

Create: pick scopes, optional brand restriction, and optional expiry. The full key is shown once at creation time and never again.
Rotate: create a new key, deploy it, then revoke the old one. There is no “regenerate” button on purpose. Explicit rotation makes overlapping keys the default and prevents downtime.
Revoke: disables the key immediately. In-flight requests still complete; the next call returns invalid_api_key.
Expire: keys with an expires_at start returning expired_api_key once the timestamp passes. Use this for short-lived integrations.

Storage hygiene

Treat keys like database passwords. Never commit them, never log them, never put them in client-side code.
Prefer your platform’s secret manager (AWS Secrets Manager, GCP Secret Manager, Vercel/Netlify env vars, Doppler, 1Password CLI).
Rotate immediately on suspected exposure; we cannot revoke retroactively what has already been read from your codebase.