> ## Documentation Index
> Fetch the complete documentation index at: https://ara-90a60a07.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```bash theme={null}
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](https://ara-90a60a07.mintlify.site/docs/mcp.md) |
| 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](https://ara-90a60a07.mintlify.site/docs/build/computers.md).

## 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](https://ara-90a60a07.mintlify.site/docs/network-policies.md).
* 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

```bash theme={null}
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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.