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.

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.

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.

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.

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:

{
  "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.

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.

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.

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.

Sending a key

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

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 for the full error semantics.

Next steps

• API reference — the endpoints each scope unlocks.

• MCP connector — OAuth 2.1 access tokens for AI clients.