> For the complete documentation index, see [llms.txt](https://ovion-studio.gitbook.io/keryo-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ovion-studio.gitbook.io/keryo-docs/developers/authentication.md).

# Authentication

Create scoped API keys, understand the scope list, and authenticate REST requests.

Programmatic access to the Keryo REST API is authenticated with **API keys**. Each key is **scoped** — it can only perform the actions its scopes grant. This page covers creating and managing keys, the full scope list, and how to send a key on a request.

{% hint style="info" %}
The MCP connector authenticates with **OAuth 2.1 access tokens** instead of API keys. If you're building or connecting an AI client, see [MCP connector](/keryo-docs/developers/mcp-connector.md).
{% endhint %}

## Managing API keys

API keys are managed at the `/api-keys` endpoints. Key management is **web-app / session only**: you must be signed in with a cookie session to create, list, update, or delete keys.

{% hint style="warning" %}
**A key cannot manage keys.** An API key can never mint or revoke other keys — that requires a logged-in session. This limits the blast radius of a leaked key.
{% endhint %}

| Method   | Path            | Description                            |
| -------- | --------------- | -------------------------------------- |
| `GET`    | `/api-keys`     | List your keys (masked previews only). |
| `POST`   | `/api-keys`     | Create a key with `{name, scopes}`.    |
| `PUT`    | `/api-keys/:id` | Update a key (e.g. name or scopes).    |
| `DELETE` | `/api-keys/:id` | Delete (revoke) a key.                 |

### Creating a key

Send a name and the scopes you want the key to carry:

```json
{
  "name": "CI publisher",
  "scopes": ["posts:read", "posts:write", "posts:publish"]
}
```

The response includes the **secret key value exactly once**, on creation. Store it securely — it cannot be retrieved again.

{% hint style="danger" %}
**The secret is shown only once.** After creation, `GET /api-keys` returns only a **masked preview** (never the full secret). If you lose a key, delete it and create a new one.
{% endhint %}

> *Response bodies for `/api-keys` are illustrative; only the `{name, scopes}` request shape and the "secret shown once, masked afterward" behavior are specified.*

## Scopes

Every API key and OAuth 2.1 token carries a set of scopes. The exact scope list:

| Scope           | Grants                                                      |
| --------------- | ----------------------------------------------------------- |
| `accounts:read` | Read client workspaces and their connected social accounts. |
| `posts:read`    | List and read posts in a workspace.                         |
| `posts:write`   | Create and update draft posts (including importing).        |
| `posts:publish` | Publish posts immediately and schedule/reschedule them.     |
| `stats:read`    | Read per-platform analytics and snapshots.                  |

Grant a key only the scopes it needs. A request that hits an endpoint requiring a scope the key doesn't hold is rejected with `403`.

{% hint style="info" %}
**Cookie sessions carry no scopes.** A signed-in web-app session has full access and is not subject to scope checks. Scopes only apply to API keys and OAuth 2.1 access tokens.
{% endhint %}

## Sending a key

Send the key in the `Authorization` header as a Bearer token:

```bash
curl https://api.keryo.io/posts \
  -H "Authorization: Bearer <your-api-key>"
```

## Plan-tier gating

Having the right scope is necessary but not always sufficient — some actions also require a minimum **plan tier**:

* `POST /posts/import` (importing existing posts) requires **Freelance** or higher.
* The `/statistics` endpoints require **Studio** or higher (in addition to `stats:read`).

A token with the correct scope but an insufficient plan is rejected with `403`. See [Rate limits & errors](/keryo-docs/developers/rate-limits-and-errors.md) for the full error semantics.

## Next steps

* [API reference](/keryo-docs/developers/api-reference.md) — the endpoints each scope unlocks.
* [MCP connector](/keryo-docs/developers/mcp-connector.md) — OAuth 2.1 access tokens for AI clients.