API keys & scopes¶

An AI client connects to Specivo with an API key — a secret string that authenticates it as a specific user. Keys are how you give an agent access without sharing a password, and how you take that access away again.

Create a key¶

1. Open Your profile → API keys (/my/api-keys/).
2. Click New API Key and give the key a clear name (for example, claude-code or ci-agent).
3. Optionally, tick the projects the key should be limited to under Limit to projects (optional) (see Limit a key to some projects). Leave every box unticked for a key that reaches all projects you can see.
4. Click Create key, then copy the key when it's shown. It looks like spv_your_api_key_here, a string that always starts with spv_.

The Projects column of the key list shows what each key reaches: All projects, or Limited to: followed by the project keys.

What a key can reach¶

Any active key works over both the REST API and the MCP server; there is no separate MCP scope to select. What the key can do is decided by its owner's permissions, and optionally by a project limit (below).

A key never grants more than its owner already has. The agent acts as the user the key belongs to, so it inherits exactly that user's project roles and permissions — no project membership, no access.

Limit a key to some projects¶

A key can be limited to some projects when it is created. In the create form, tick those projects in the Limit to projects (optional) list. It lists the projects you can see; with more than 15 a filter box above the list finds them by key or name. The line under the list says what the key will reach: "Nothing ticked" means every project you can see, otherwise it names the ticked projects.

Over the REST API, pass scopes in the body of POST /api/v1/my/api-keys/, naming each project by key or by id:

{
  "name": "ci-agent",
  "scopes": {"projects": ["ACME", "OPS"]}
}

The key then reaches only those projects, over the REST API, the web pages and MCP alike, even when its owner can see more:

• everything in another project behaves as if it did not exist: reading or listing it, searching it, and writing to it all answer not found, and lists, search results, relations, history entries and people pickers leave it out;
• a key of an administrator keeps its administrator rights inside its projects only, and cannot use instance-wide administration (403);
• a limited key cannot manage API keys, sessions or the password of its owner (403), so it cannot create itself an unlimited key.

Leave scopes out for a key that reaches every project its owner can. The request is refused (422, on the scopes field) when the list is empty, when scopes holds anything but projects, or when a project does not exist or is one you cannot see. Up to 200 projects can be named.

Specivo stores the limit as project ids, so renaming a project key does not change what the key reaches. The key list (GET /api/v1/my/api-keys/) shows the limit as project_keys, for example ["ACME", "OPS"], or null for a key that is not limited. A project deleted later drops out of the list; a key whose projects are all gone reaches nothing.

An administrator can create a limited key for a service account the same way: on the account's page in Admin → Users, which has the same project list under the key name, or through POST /api/v1/admin/users/{id}/api-keys/ from a signed-in session. There the list holds every project and the projects only have to exist: the account can be added to them afterwards, and the key never reaches more than the account's own roles allow. The account's key list shows the limit the same way.

The limit is fixed when the key is created. To change it, create a new key and revoke the old one.

Use a dedicated service account¶

Issuing an agent a key from your own personal account works, but it mixes the agent's actions in with yours and ties its access to your login. The cleaner pattern is a dedicated service account:

1. Create a separate user (for example, agent or claude) for the automation.
2. Add that user to the relevant projects with the Agent role, which is built for API and automation accounts.
3. Generate a key from that account and hand it to the client.

This keeps the agent's audit trail and permissions distinct from any person's, and lets you adjust or revoke its access without touching real users' accounts.

Rotate and revoke keys¶

Treat API keys like passwords: rotate them periodically, and revoke any key you no longer use or suspect is exposed. To rotate, create a new key, update the client's configuration to use it (see Connecting an AI client), then revoke the old one.

Keys can also be switched off for you. Deactivating an account switches off all of its keys, and so does a back-channel logout from an identity provider set to End all of their sessions and switch off their API keys, for a person who signs in only through single sign-on (see What a back-channel logout ends). Signing in again does not switch them back on: do that on your API keys page, or create new ones.

What an administrator's key cannot do¶

A key belonging to an administrator can run most administration through the API: reading users, locking or deactivating an account, revoking keys, project and workflow settings. It cannot do anything that hands out a way to sign in or to act as somebody else. These need an administrator signed in to Specivo, and a key gets 403 with the code api_key_not_allowed:

• resetting a user's password (POST /api/v1/admin/users/{id}/reset-password/);
• creating any account other than a service account (POST /api/v1/admin/users/): a person, an administrator, or an account with a password. A key can still create service accounts for agents (is_service_account: true, no password);
• unlocking or reactivating an account (POST /api/v1/admin/users/{id}/unlock/, .../reactivate/, and the Reactivate button when called with a key);
• creating an API key for a user (POST /api/v1/admin/users/{id}/api-keys/);
• changing single sign-on: creating, editing or deleting identity providers and their group mappings, and saving the authentication settings (see Single sign-on).

So a leaked administrator key cannot turn itself into a signed-in session, for example by resetting another administrator's password, and cannot add an identity provider that makes its users administrators. Taking access away stays possible with a key, so incident automation keeps working.