Authentication and scopes

Choose how your app signs in to Reason: API keys with scopes, MCP OAuth, a CLI login, or a Machine token. One table lists the scopes.

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

reason whoami

​

The four ways in

Who acts	Credential	How you get it
Your product, a script, a server	API key (reason_…; legacy ara_… still accepted)	Settings > API. Send Authorization: Bearer KEY.
A coding agent over MCP (Claude Code, Codex)	MCP OAuth, or an API key in the header	Connect an agent over MCP
You, from a terminal or editor	CLI login	reason login, or reason login --pair CODE from Settings > Network to choose the Workspace
A Machine (a server you share as a computer)	Machine token (rmt_…)	reason machines token NAME

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.

Scope	Lets the holder
run	Create, send to, cancel, archive and delete Sessions
sessions:read	Read Sessions and their assistant, reasoning and tool events
sessions:debug	Read the full diagnostic events (owner/admin only)
devices:read	List your computers and their folders
computers:read	List every computer you can use, cloud included (GET /v3/organizations/{orgId}/computers); opt-in, not in default keys
devices:use	Run work on a computer you connected (needed for computer-backed Sessions)
devices:write	Connect, rename or change a computer and its folders
deployment:read	Read deployment identity, and send images with a key
org:read / org:write	Read or change the organization (org:write is owner/admin)
mcp:read / mcp:write	Read MCP servers, or change their configuration (mcp:write does not run remote MCP tools)
secrets:read / secrets:write	Read secret names, or store values
skills:read / skills:write	Read or change Workspace skills
memory:read / memory:write	Read or change memory files
repos:read / repos:write	Read or change repository connections
automations:read / automations:write	Read or change automations
network:read	Read the saved network policy
network:write	Replace custom allowed hosts (owner/admin only)
guardrails:read / guardrails:write	Read or change guardrails
attachments:read / attachments:write	Read or upload attachments
agent_auth:read	Read available models and inference status

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

curl -fsS -H "Authorization: Bearer $REASON_API_KEY" https://api.reasonmachines.com/v3/self

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.