> ## 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.
# Approve a worker with a Machine token
> Approves one headless worker installation for the Machine that the token belongs to, in the token's Workspace. Authenticate only with the Machine token (`Authorization: Bearer rmt_...`); API keys and OAuth tokens are rejected. The body and one-use ticket are identical to createMachineEnrollmentTicket; the response also names the Workspace and Machine, so a worker needs no other configuration. Tickets are owned by the token creator and stop working if the creator is no longer an owner or admin. Execution feature gates can return 503.
Auth: Machine token (`rmt_...`) only; API keys and OAuth tokens are rejected
## OpenAPI
````yaml /openapi.json post /v3/machines/enrollment-tickets
openapi: 3.1.0
info:
title: Reason Machines API
version: 3.0.0
description: >-
The Reason HTTP API. Drive cloud software-engineering agents: open sessions
against your repositories, stream their work, and manage the secrets,
knowledge, skills, and automations they run with.
Authenticate with a Reason API key sent as a bearer token. New keys use
`reason_`; legacy `ara_` keys remain accepted. Every resource is scoped to
an organization; resolve your `org_id` once with `GET /v3/self`.
servers:
- url: https://api.reasonmachines.com
security:
- reasonApiKey: []
tags:
- name: Devices
description: >-
Owned Mac and headless Device identity, bounded enrollment and root
grants.
- name: Machines
description: >-
Named Workspace queues served by headless workers. Sessions target a
Machine by name and wait for a free worker; more workers serve more
Sessions concurrently.
- name: Account
description: Verify a key and resolve the organization it belongs to.
- name: Projects
description: >-
Discover existing workspace projects to target when creating and listing
sessions.
- name: Sessions
description: >-
A session is one run of an agent against a repository: it reproduces the
task, writes the code, verifies it, and opens a pull request or merge
request.
- name: Secrets
description: >-
Encrypted credentials injected into the agent's sandbox. Write-only:
values can be set but never read back.
- name: Knowledge
description: Durable notes the agent consults while it works.
- name: Memory
description: >-
Editable repository notes that are projected into native memory; generated
memory remains read-only.
- name: Skills
description: >-
Reusable instruction bundles Reason selects semantically from their
descriptions for matching agent tasks.
- name: Automations
description: Recurring or one-time triggers that open sessions on a timetable.
- name: Change Request Reviews
description: >-
Automated senior-engineer reviews posted on pull requests and merge
requests.
- name: Repositories
description: Connected repositories, their indexing state, and generated wikis.
- name: Git Connections
description: Linked source-control accounts and the repositories they expose.
- name: Consumption
description: 'Billing-aligned usage: daily consumption and billing cycles.'
- name: Metrics
description: Aggregate analytics over sessions, change requests, and usage.
- name: Audit Logs
description: An append-only record of changes made within the organization.
- name: Organizations
description: The top-level tenant. Create, read, update, and delete organizations.
- name: Members
description: People in an organization and their pending invites.
- name: Service Users
description: Machine principals that own API keys for headless access.
- name: Roles
description: Role assignments that govern what each member can do.
- name: Attachments
description: >-
Files uploaded to the organization and shared with sessions, downloaded
via short-lived signed URLs.
- name: Guardrails
description: >-
Per-repository automation limits and the violations recorded when a limit
is hit.
- name: MCP Servers
description: >-
Org-level Model Context Protocol servers exposed to the agent. Secret
values are write-only.
- name: Settings
description: 'Organization configuration: namespaced settings and the run tag policy.'
- name: Blueprints
description: >-
Read-only declarative manifests of an organization's agents (identity, run
config, triggers, suite), with credentials redacted.
- name: IP Access List
description: >-
Source-network allow-list that, when enabled, restricts the organization's
API surface to a set of CIDR ranges.
- name: Groups
description: Manually-curated member groups carrying optional per-day resource limits.
- name: Provider Credentials
description: >-
Configure Bring-Your-Own-Key (BYOK) API keys and subscription credentials
for model providers. Secret values are write-only.
paths:
/v3/machines/enrollment-tickets:
post:
tags:
- Machines
summary: Approve a worker with a Machine token
description: >-
Approves one headless worker installation for the Machine that the token
belongs to, in the token's Workspace. Authenticate only with the Machine
token (`Authorization: Bearer rmt_...`); API keys and OAuth tokens are
rejected. The body and one-use ticket are identical to
createMachineEnrollmentTicket; the response also names the Workspace and
Machine, so a worker needs no other configuration. Tickets are owned by
the token creator and stop working if the creator is no longer an owner
or admin. Execution feature gates can return 503.
Auth: Machine token (`rmt_...`) only; API keys and OAuth tokens are
rejected
operationId: createMachineTokenEnrollmentTicket
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateDeviceEnrollment'
responses:
'201':
description: One-use ticket bound to the token's Machine.
content:
application/json:
schema:
$ref: '#/components/schemas/MachineTokenEnrollmentTicket'
example:
enrollment_ticket: illustrative-one-use-ticket
expires_at: '2026-09-26T09:02:00Z'
device_kind: headless
lifecycle: persistent
device_expires_at: '2026-10-26T09:00:00Z'
machine_id: 22222222-2222-4222-8222-222222222222
machine_name: build-box
organization_id: 11111111-1111-4111-8111-111111111111
'400':
description: Invalid approval.
'401':
description: Missing, invalid or revoked Machine token.
'403':
description: >-
The token creator is no longer an owner or admin, or the Workspace
IP policy denies the request.
'429':
description: Too many requests for this token.
'503':
description: Device execution unavailable.
security:
- reasonMachineToken: []
components:
schemas:
CreateDeviceEnrollment:
type: object
properties:
install_id:
type: string
minLength: 16
maxLength: 160
code_challenge:
type: string
pattern: ^[A-Za-z0-9_-]{43}$
lifecycle:
type: string
enum:
- persistent
- ephemeral
ttl_seconds:
type: integer
minimum: 60
roots:
minItems: 1
maxItems: 32
type: array
items:
type: object
properties:
path_fingerprint:
type: string
pattern: ^[a-f0-9]{64}$
permissions:
type: object
properties:
read:
type: boolean
write:
type: boolean
execute:
type: boolean
discover_environment:
type: boolean
expose_mcp:
type: boolean
const: false
required:
- read
- write
- execute
- discover_environment
- expose_mcp
additionalProperties: false
execution_mode:
default: confined
type: string
enum:
- confined
- host
required:
- path_fingerprint
- permissions
additionalProperties: false
required:
- install_id
- code_challenge
- lifecycle
- roots
additionalProperties: false
description: >-
Single-use P-256/PKCE headless enrollment. Persistent TTL defaults to 30
days (maximum 90 days); ephemeral defaults to 1 hour (maximum 24 hours).
Minimum TTL is 60 seconds. Root fingerprints and permissions are the
approval ceiling; unknown fields, including device_kind and
bound_run_id, are rejected.
MachineTokenEnrollmentTicket:
type: object
properties:
enrollment_ticket:
type: string
expires_at:
type: string
device_kind:
type: string
const: headless
lifecycle:
type: string
enum:
- persistent
- ephemeral
device_expires_at:
type: string
machine_id:
type: string
format: uuid
pattern: >-
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
machine_name:
type: string
organization_id:
type: string
format: uuid
pattern: >-
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
description: Workspace the worker redeems the ticket in.
required:
- enrollment_ticket
- expires_at
- device_kind
- lifecycle
- device_expires_at
- machine_id
- machine_name
- organization_id
securitySchemes:
reasonApiKey:
type: http
scheme: bearer
bearerFormat: 'reason_ (legacy: ara_)'
description: >-
Your Reason API key from Settings > API. New keys use `reason_`; legacy
`ara_` keys remain accepted. Keys are capability-scoped: run, mcp:read,
mcp:write, secrets:read, secrets:write, sessions:read, sessions:debug,
knowledge:read, memory:read, memory:write, skills:read, skills:write,
repos:read, repos:write, reviews:read, reviews:write, deployment:read,
analytics:read, org:read, org:write, attachments:read,
attachments:write, guardrails:read, guardrails:write, automations:read,
automations:write, agent_auth:read. mcp:write manages MCP server
configuration only; it does not authorize remote MCP-tool execution.
sessions:debug is privileged: it expands diagnostic session events only
for organization owners/admins.
reasonMachineToken:
type: http
scheme: bearer
bearerFormat: rmt_
description: >-
A Machine token from createMachineToken. It can only create enrollment
tickets for its own Machine; every other operation rejects it.
````