How-To Guides / Admin
Choose a Key Scope
Every Telara API key is created at a scope — tenant, team, project, or user. The scope sets who the key is for and, when you send agent telemetry, how each run is attributed to a person. Pick the scope that matches how the key will be used.
The Four Scopes
What each scope means
Available to your entire organization.
A shared backend or service that serves many people. One key for the whole org.
Runs are attributed to whoever you name in the SDK (workflow(user=...)). If you name no one, the run is recorded for the org but left unattributed.
Admins only.
Available to a specific team.
A team’s shared agent or automation. Everyone on the team uses the same key.
Same as tenant — attributed to the user you name in the SDK, within that team.
Team maintainers (or admins).
Available to a specific project.
An agent tied to one project that several collaborators share.
Attributed to the user you name in the SDK, within that project.
Project maintainers (or admins).
Available to one individual.
A single developer, a personal CLI, or a per-person key. The strongest attribution.
Every run is automatically attributed to that user — you do not need to name anyone, and any user you name in the SDK is ignored.
The user themselves, or an admin.
At a Glance
Which scope should I pick?
How To
Create a key at a scope
telara_mcp_.If a configuration is deployed at the tenant level, you can create keys at any scope. If it is deployed only to a team, you can create team or user keys — not tenant or project. Deploy at a broader scope first if you need broader keys.
Attribution
How scope changes who a run belongs to
When you send agent telemetry with the telara-observability package, the key scope decides how each run is attributed:
Every run is attributed to that one user automatically. Anyone you name in the SDK is ignored, so the attribution can't be set to someone else. Best for per-developer keys.
Runs are attributed to whoever you pass to workflow(user=...) (or with_user(...)). This is what a shared backend uses to attribute each request to the right person. Because the SDK asserts the user, use a user-scoped key when you need attribution to be tamper-proof.
Use an email that matches your directory so runs map to the right person in reports; unmatched users are still recorded, just flagged as unmapped.