Skip to content
RankabilityRankability Help Center

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

Section titled “Create and store a key”

Only an organization owner or admin can manage keys. Open 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

Section titled “Send the Bearer header”

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

Authorization: Bearer rk_live_YOUR_KEY
Terminal window
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

Section titled “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
Prospect reports prospect_scan:run Run an agency-owned AI visibility report without creating a client or Tracker project
Prospect reports prospect_scan:read Read the agency’s report status, result, and submitted lead email
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 Start durable page optimization runs and read saved results
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 usage impact
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
Prospector prospector:read Read saved outreach lists and pipeline items
Prospector prospector:write Create, update, and delete saved outreach lists and items
Backlink profile backlinks:read Read saved backlink profile evidence without provider refresh
Backlink profile backlinks:run Create or refresh saved aggregate backlink profile evidence after approval
GBP Auditor gbp-audit:read Read saved GBP audit artifacts without starting an audit
Batch URL Analyzer batch-url:read Read saved run history without analyzing URLs
Routines routines:read Read recurring content and Knowledge-monitor Routine state without changing schedules
Publishing publishing:read Read credential-free connections and privacy-safe delivery receipts
Publishing publishing:write Prepare immutable article snapshots and request confirmed draft-only delivery; never publish live
Serena serena:ask Ask client-scoped strategic questions through the read-only consultation endpoint
SEO Researcher seo_research:run Start an SEO research job
SEO Researcher seo_research:read List jobs and read a job’s status and saved result

The SEO Researcher scopes apply to the standalone SEO Researcher product. Like Copywriter Core, it is entitled separately from the full platform, so a key carrying those scopes only reaches that product’s endpoints.

Apply least privilege

Section titled “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.
  • An outreach dashboard needs prospector:read; grant prospector:write only when it will change saved list state.
  • A backlink dashboard that only reads saved evidence needs backlinks:read. Grant backlinks:run separately only when it must create or refresh aggregate snapshots after an estimate and explicit approval. Neither scope authorizes individual-backlink export.
  • Saved GBP and Batch URL reporting use gbp-audit:read and batch-url:read; neither scope starts provider-backed work.
  • Routine and publishing dashboards use routines:read and publishing:read; these scopes cannot change a schedule, deliver content, retry, validate, reconnect, or expose credentials. Grant publishing:write separately only when the integration must request a confirmed draft delivery. That scope still cannot publish live.
  • Serena consultation uses serena:ask; it can read the selected client’s grounded context but cannot run scans, change projects, publish, or perform live web research.

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

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

API and MCP access follows the same account rule as signing in to Rankability. An active subscription, a trial, a subscription inside the payment-retry window, a cancelled account that still holds purchased credits, or a standalone product entitlement all keep working. A fully lapsed account returns 403 subscription_required on every request, not only when you create a key.

Diagnose authentication failures

Section titled “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’s access has lapsed, so it cannot create a key or make API requests Reactivate the subscription in Settings → Billing

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 usage, rate limits, and errors.