> 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

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