> For the complete documentation index, see [llms.txt](https://help.rankability.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.rankability.com/api/api-authentication.md).

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

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

```http
Authorization: Bearer rk_live_YOUR_KEY
```

```bash
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`              | 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                                     |
| 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

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`; this scope does not authorize provider refresh or 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

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](/api/api-getting-started.md) or review [API usage, rate limits, and errors](/api/api-credits-rate-limits-and-errors.md).