Skip to main content
Every Reason call is signed in one of four ways. Pick the one that matches who is acting.

​
What you will have

  • A credential for your app, with only the scopes it needs.
  • A check that proves the credential reaches the right Workspace.

​
Prerequisites

​
The four ways in

A key belongs to one Workspace. Confirm which one with GET /v3/self, which returns org_id, the organization name, and the scopes the credential holds.

​
Scopes

Grant a key only what it uses. Scopes marked “owner/admin” can be minted only by a workspace owner or admin. Keys without computers:read keep the devices list in Computers.

​
Rules that surprise people

  • A key with run alone cannot run work on a computer. Device-backed Sessions also need devices:use.
  • sessions:read returns assistant, reasoning and tool events. Treat a key that holds it as able to read what the agent did.
  • Network policy writes need network:write and an owner or admin role. See Manage network policies.
  • Keys cannot grant themselves more authority. Rotate a key by creating a replacement with the scopes it needs, then deleting the old one in Settings > API.

​
Check it works

The response names the organization and lists scopes. A wrong key returns 401. A key missing a scope returns 403 with missing_scope and the scope it needs.