Authentication and API scopes

Create, secure, rotate, and scope Rankability Agent API keys with the minimum access each integration requires.

Rankability Agent API keys are organization-scoped Bearer credentials. Use a separate least-privilege key for each integration so access can be changed or revoked without affecting other systems.

Create and store a key

Only a workspace owner or admin can manage keys in Settings → API keys. An active subscription is required.

When creating a key, provide:

• A descriptive name.

• One or more scopes.

• An optional expiration date.

Rankability displays the complete rk_live_... secret once. Store it in a server-side secret manager. Never place it in client-side JavaScript, a public repository, an analytics property, a support ticket, or a shared document.

Send the Bearer header

Send the key on requests to the Agent API base URL:

Authorization: Bearer rk_live_YOUR_KEY

curl https://app.rankability.com/api/agent/v1/clients \
  -H "Authorization: Bearer rk_live_YOUR_KEY"

Do not send the key to any host other than https://app.rankability.com.

Current scopes

Product area	Scope	Permission
Copywriter	copywriter:run	Create or continue content work
Copywriter	copywriter:read	Read jobs, artifacts, and exports
Tracker	reporter:read	Read projects, results, trends, and summaries; the scope name is retained for compatibility
Tracker	reporter:run	Start tracking scans; the scope name is retained for compatibility
Tracker	reporter:write	Create, update, and delete tracking projects; the scope name is retained for compatibility
Researcher	researcher:run	Start keyword-research jobs
Researcher	researcher:read	Read jobs and saved projects
Clients	clients:read	List and read clients
Clients	clients:write	Create, update, and delete clients
Help knowledge base	kb:read	Read published knowledge-base content
Optimize	optimize:run	Run synchronous page optimization analysis
Page Auditor	page_audit:read	Read and list page audits
Page Auditor	page_audit:write	Start and delete page audits
Site Auditor	site-auditor:read	List audits, read results, and estimate cost
Site Auditor	site-auditor:write	Create, crawl, cancel, and delete audit projects
Search Intelligence	search_intelligence:query	Run and retrieve search-intelligence queries
Crawler	scrape:run	Fetch one page
Crawler	crawl:run	Start and poll a bounded crawl
Crawler	extract:run	Extract structured answers from content

Apply least privilege

Choose scopes based on actions, not convenience:

• A dashboard that only reads tracking data normally needs reporter:read.

• A scheduled scan runner needs reporter:read and reporter:run, but not reporter:write unless it manages projects.

• A Researcher automation that starts and polls jobs needs researcher:run and researcher:read.

• A Site Auditor integration that only exports completed findings needs site-auditor:read.

• A crawler integration needs separate scopes for scrape, crawl, and extract; grant only the operations it actually calls.

Routes requiring several scopes require all listed permissions. Routes documented as accepting any of several scopes require at least one.

Update, rotate, or revoke a key

From Settings → API keys, an owner or admin can:

• Change a key's name or scopes.

• Review its prefix, creation time, expiration, and last-used time.

• Revoke it permanently.

The expiration cannot be extended by editing the existing key. Create a replacement when rotating or changing expiration, update the integration, verify the new key, and then revoke the old key.

Revocation is permanent. A revoked, expired, suspended, or unknown key returns 401 unauthorized.

Diagnose authentication failures

Response	Meaning	Action
401 unauthorized	Missing Bearer header or invalid, expired, revoked, or suspended key	Confirm the header and rotate the key if necessary
403 forbidden	Valid key without the required scope	Add only the required scope or use the correct integration key
403 subscription_required	The organization cannot create a key without an active subscription	Restore subscription access before creating a key
404 session_reinitialize_required	The MCP session expired or belongs to a different credential principal	Initialize a new MCP session with the current credential

Record the response's X-Request-Id when contacting support. Never send the full key.

Next, make a request with Getting started with the API or review API credits, rate limits, and errors.