Why does my project API key get a 403 saying it only reads one project and records findings in it?

Tares returns this 403 because a project key is scoped to one project. It reads that project, records findings in it and manages its own subscriptions to it, and every other call is refused with that message. Make a key under the project’s Settings, Keys and copy the secret, which is shown once. Tares checks keys only on a secured instance.

How it works

A project key is the credential you give an agent that runs outside Tares, such as Claude Code, Codex or your own service. It works inside one project, and the 403 tells you the call went outside what the key allows.

What a project key can do:

• Read the project. POST /read and stats cover the project’s sources, plus the findings recorded in this project. GET /api/projects and /catalog show this project only.
• Read the project’s own material. Its skills, timeline, findings, results, outline and health are readable. Another project’s are not.
• Record findings in the project.
• Manage its own subscriptions to the project. A key can remove only the subscriptions it made itself.

Everything else answers 403 with the message: this key only reads project (your project’s name) and records findings in it. For example, a call that reads a different project, or that changes a source, trigger or agent, gets this answer.

Keys are checked on a secured instance, which is one started with TARES_AUTH_TOKEN. On an open instance nothing is checked and there are no keys to hand out. The MCP tools then take the project by name.

The scope is deliberate. The agent that holds the key can only touch the one project you made the key for. If you revoke the key, the agent loses access straight away.

Set it up

1. Open the project in the console and go to its Advanced setup.
2. Open Settings, then Keys.
3. Make a key. Name it after who holds it, because the findings it records carry that name. Do not give it the name of one of your Tares agents, because a key with such a name cannot record findings and gets a 409.
4. Copy the secret straight away. It is shown once, and the key list never shows it again.
5. Give the secret to the outside agent, and have it use only the calls the key allows. To record a finding in the project, it posts a body like this to the project’s findings route:

{ "entity": "checkout", "finding": "Errors began after deploy 9f2c81d ...", "verdict": "rca", "label": "service" }

6. Check the field rules. entity is what the finding is about. finding is markdown, up to 64 KB. verdict is optional, one lowercase word such as rca or resolved. label is the label the entity is a value of. If you leave it out, Tares uses the entity label of the project’s first trigger. headline and next_step are optional too.
7. To be woken by the project’s triggers, the agent joins with POST /api/projects/{id}/subscribe or the MCP tool join_project(url). A project key manages its own subscriptions, so this call works with it.
8. To cut an agent off, use Revoke under Settings → Keys. Revoking a subscription from the project’s Agents section stops its deliveries, but the key keeps working until you revoke it under Keys.

If you still get the 403 after this, read the path you are calling. Anything outside the list above, such as another project’s data, is refused by design.

What you get

• An outside agent that works inside exactly one project and cannot reach anything else.
• Findings that land on the entity’s timeline. Every later read of that entity includes them, and a trigger over the findings source can fire on them.
• A card for each finding under What the agents found on the project Overview. In Activity it is a thread marked as recorded from outside Tares. The card carries the key’s name as its agent, so you can see who recorded it.
• Project-scoped reads. The agent sees the project’s sources, skills, timeline, results, outline and health, and no other project’s.
• A quick way to stop access. Revoke cuts the key off, and deleting the project revokes its keys and ends the subscriptions of the agents that joined it.

A clear 403 therefore means the key is working as designed, not that it is broken.

When something else fits

• If your instance is open, with no TARES_AUTH_TOKEN, keys are not checked at all, so you will not see this 403 there. Use the MCP tools, which take the project by name.
• If you need to change sources, triggers or agents, do it in the console on the project page, because a project key is for reading and recording findings only.
• To see how a project fits an incident workflow, read Build an AI SRE.

Related