Credentials and scopes
How to get a project key, what each permission allows, and why a key that stages changes cannot approve them. Preview.
Preview. The tools that use these keys are in preview and may change.
An agent reaches your project with an API key. This page explains how to get one, what its permissions mean, and how a key decides which project an agent is working in.
Get a key
In the Workspace, open your project's settings, go to the API keys tab and choose Create API key.
- Name the key for the person or machine that will use it.
- Choose its permissions (scopes), from the table below.
- Choose an expiry: 30 days, 90 days, 1 year, a date of your own, or never. A key that never expires stays valid until someone revokes it; prefer a dated expiry and rotate.
- Copy the credentials from the last screen: a client id, a client secret, a token address and an API address, with a
.envblock ready to paste. The secret is shown once. You cannot see it again; if you lose it, create a new key and revoke the old one.
Revoke a key from the same tab.
Keep the secret in a .env file that is not committed, or in your secret store. Never paste it into a chat with an agent, and never pass it as a command-line flag. One project, one key per person or machine is easier to revoke than one shared key.
Scopes
| Scope | Allows | Give it to an agent? |
|---|---|---|
context:read | Read and search the context, list kits, releases and the open change request | Yes. Every agent needs it |
context:assets | Stage proposed changes to assets (pages, entities, skills, pointers and links) for review | Yes, for an agent that proposes changes |
context:kits | Create, change, retire or revert a kit. A kit write takes effect at once, but a kit can hold only assets that are already published | Yes, for an agent that manages kits |
context:gaps | Record, change, close or revert a gap (something your context is missing) | Only when you want the agent to manage gaps |
context:review | Decide staged changes, merge a change request into a release, or close it | No. This is what publishes; a person holds it |
A key can hold several. The plugin and the command line ask for only the scope an action needs, and request context:kits or context:gaps only when you ask for kit or gap work.
Why a key that stages cannot approve its own work
Staging and settling are separate permissions. context:assets lets a key propose; it opens nothing that approves, merges or closes. Those need context:review, which the plugin and the command line never request. So an agent given the keys from Getting started can fill your change request but cannot publish it. A person reviews it in the Workspace and merges it.
A key decides the project
Every key belongs to one project. The key's token names it, and the client sends requests to the API address with nothing project-specific in the path. A key for project A cannot read or change project B: asking for B's data answers not found.
To make sure a session is talking to the project you intend, pin it:
- the command line takes
COELEVATE_PROJECT_ID(or--expect-project); - the plugin reads the project from
.coelevate.jsonin your folder (see Plugin).
If the key reaches any other project, the action is refused before it reads or stages anything, and the message names both projects. For the command line that is exit code 2. For the plugin, the hook loads no kits and tells the agent to stop.