Authentication
API keys, the roles they carry, and keys pinned to one client.
Embed
<a href="https://seolyticize.com/docs/authentication"><img src="https://seolyticize.com/docs/_api/public/orgs/71cb2b7a-a719-4003-b3ea-6321dc1db8ab/spaces/3bf2dbf7-3faa-473c-ba3b-30588f5f8de4/pages/504c8e37-0ae4-4e99-9ef3-e7c56e3d547f/social-card.svg?v=3e7ae33eec8b" alt="Authentication" width="600" height="315"></a>Every call carries an API key as a bearer token:
Authorization: Bearer sk_seo_…The same key works on REST, on the MCP server, in the SDK and in the command line. Assistants can also sign in through OAuth instead of using a key; see MCP server.
Create a key
Keys are made in the app under Settings → API keys, by an owner or admin of the agency. An existing key with the admin role can also create one with the create_api_key tool.
The secret starts with sk_seo_ and is shown exactly once. Only a hash of it is stored, so a lost key is replaced, not recovered. Keep it in an environment variable or a secret store, never in source code.
Agency-wide or one client
A key is either:
agency-wide — it can reach every client the agency has; or
pinned to one client — it cannot reach any other client's data, on any surface.
A pinned key is what makes it safe to hand a key to an integration or an assistant that works for a single customer: whatever it is asked, it can only see that one client.
Roles
Each key carries a role, and the role decides which tools the key may call. A key can never be an owner.
Role | Can |
|---|---|
| Read only. Cannot write, spend or send anything. |
| Read, write data and send reports. |
| The default. Also spends money (live lookups, crawls, submissions) and manages projects. |
| Also manages clients and API keys, and agency settings. |
A key pinned to one client is capped at manager: admin powers are agency-wide by nature.
Every tool declares the permission it needs, and the roles map onto them like this:
Permission | Lets a tool |
|
|
|
|
|---|---|---|---|---|---|
| read data | ✓ | ✓ | ✓ | ✓ |
| change data (keyword lists, notes, rank trackers…) | ✓ | ✓ | ✓ | |
| send reports | ✓ | ✓ | ✓ | |
| make calls that cost money | ✓ | ✓ | ||
| read what the agency spent | ✓ | ✓ | ||
| manage projects | ✓ | ✓ | ||
| create, change and archive clients, and their alert rules | ✓ | |||
| create and revoke API keys | ✓ | |||
| change agency settings | ✓ |
You never need to work this out by hand: discovery returns only the tools your key may call.
What may this key do?
GET /api/v1/tools answers with every tool the presented key may call, and the key's own reach:
curl https://seolyticize.com/api/v1/tools \
-H "Authorization: Bearer $SEOLYTICIZE_API_KEY"{
"tools": [ { "name": "list_clients", "permission": "data:read", "…": "…" } ],
"caller": { "role": "manager", "clientIds": "all" }
}caller.clientIds is "all" for an agency-wide key, or a list holding the one client a pinned key may reach.
Revoking a key
Revoke a key under Settings → API keys, or with revoke_api_key. A revoked key is refused on its very next request, including on an MCP connection that is already open: the key is checked on every request, not once per session.