> ## 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. # Verify credentials > Returns the principal behind the current credential, its granted scopes, and the organization it can act on. Call this first to discover your `org_id` and available capabilities. ## REST quickstart 1. Create a key in Settings > API. Send it only in `Authorization: Bearer `, never in a URL. 2. Call this endpoint and keep the returned `org_id`. Creating and polling a session requires `run` and `sessions:read`. 3. Optionally discover repositories with `GET /v3/organizations/{orgId}/repositories` (`repos:read`) and Projects with `GET /v3/organizations/{orgId}/projects` (`sessions:read`). Use an accessible Project ID; selecting a Project does not automatically select its repository or execution target. 4. POST a prompt to `/v3/organizations/{orgId}/sessions`. Set `completion_mode: run_outcome` for unattended work and an `idempotency_key` in the JSON body. Retrying the same task must reuse the same key and project/target/policy. HTTP 201 creates; HTTP 200 replays. 5. Poll the returned session ID with GET until status leaves running. Lifecycle exit does not prove success: inspect `outcome`, `result`, `result_summary`, and diagnostics. Only outcome success is a successful task; failure, action_required and null need handling. Follow `Retry-After` on HTTP 429. ### Runnable Node.js example Download [api-session.mjs](https://reasonmachines.com/examples/api-session.mjs), review it, and run it with Node.js 20 or newer. It creates real work that may incur usage. Set `REASON_API_KEY`, `REASON_PROMPT`, and a stable `REASON_IDEMPOTENCY_KEY` in your environment, then run `node api-session.mjs`. Optional `REASON_REPO` and `REASON_PROJECT_ID` select resources explicitly. The example exits nonzero for failed, suspended, unresolved, or action-required tasks and times out after ten minutes without cancelling the remote session. ## MCP is a separate client connection For an MCP client, connect to `https://mcp.reasonmachines.com/mcp` using that client's supported OAuth setup. The REST workflow above uses the HTTP API and does not require installing an MCP client. Auth: any valid API key (no scope) ## OpenAPI ````yaml /openapi.json get /v3/self 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: Feedback description: Report problems with the API or these docs to the Reason team. - 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/self: get: tags: - Account summary: Verify credentials description: >- Returns the principal behind the current credential, its granted scopes, and the organization it can act on. Call this first to discover your `org_id` and available capabilities. ## REST quickstart 1. Create a key in Settings > API. Send it only in `Authorization: Bearer `, never in a URL. 2. Call this endpoint and keep the returned `org_id`. Creating and polling a session requires `run` and `sessions:read`. 3. Optionally discover repositories with `GET /v3/organizations/{orgId}/repositories` (`repos:read`) and Projects with `GET /v3/organizations/{orgId}/projects` (`sessions:read`). Use an accessible Project ID; selecting a Project does not automatically select its repository or execution target. 4. POST a prompt to `/v3/organizations/{orgId}/sessions`. Set `completion_mode: run_outcome` for unattended work and an `idempotency_key` in the JSON body. Retrying the same task must reuse the same key and project/target/policy. HTTP 201 creates; HTTP 200 replays. 5. Poll the returned session ID with GET until status leaves running. Lifecycle exit does not prove success: inspect `outcome`, `result`, `result_summary`, and diagnostics. Only outcome success is a successful task; failure, action_required and null need handling. Follow `Retry-After` on HTTP 429. ### Runnable Node.js example Download [api-session.mjs](https://reasonmachines.com/examples/api-session.mjs), review it, and run it with Node.js 20 or newer. It creates real work that may incur usage. Set `REASON_API_KEY`, `REASON_PROMPT`, and a stable `REASON_IDEMPOTENCY_KEY` in your environment, then run `node api-session.mjs`. Optional `REASON_REPO` and `REASON_PROJECT_ID` select resources explicitly. The example exits nonzero for failed, suspended, unresolved, or action-required tasks and times out after ten minutes without cancelling the remote session. ## MCP is a separate client connection For an MCP client, connect to `https://mcp.reasonmachines.com/mcp` using that client's supported OAuth setup. The REST workflow above uses the HTTP API and does not require installing an MCP client. Auth: any valid API key (no scope) operationId: getSelf responses: '200': description: The authenticated principal. content: application/json: schema: $ref: '#/components/schemas/Self' example: principal_type: service_user service_user_id: key_3f9a service_user_name: ci-bot org_id: org_8c2d1e scopes: - run - sessions:read - repos:read '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/RateLimited' security: - reasonApiKey: [] components: schemas: Self: type: object properties: principal_type: type: string enum: - service_user - user description: >- API keys resolve to `service_user`; MCP OAuth grants resolve to `user`. service_user_id: type: string description: Present when `principal_type` is `service_user`. service_user_name: description: Present when `principal_type` is `service_user`. type: - string - 'null' org_id: type: string description: Organization pinned to the current credential. scopes: type: array items: type: string description: Capabilities granted to the current API key or OAuth token. user_id: type: string description: Present when `principal_type` is `user`. user_name: description: Present when `principal_type` is `user`. type: - string - 'null' email: description: Present when `principal_type` is `user`. type: - string - 'null' organization_name: description: Display name of the organization pinned to this credential. type: - string - 'null' organization_slug: description: URL slug of the organization pinned to this credential. type: - string - 'null' mcp_connections: type: array items: type: object properties: client_id: type: string client_name: type: string last_used_at: type: - string - 'null' required: - client_id - client_name - last_used_at description: >- Active MCP OAuth client grants for the signed-in user and organization. required: - principal_type - org_id - scopes Error: type: object properties: error: oneOf: - type: string - type: object required: - type - message properties: type: type: string message: type: string request_id: type: - string - 'null' message: type: string required_scope: type: string description: >- The capability required when the request was denied for a missing scope. responses: Unauthorized: description: Missing, invalid, or expired key. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: missing_bearer message: Authorization required Forbidden: description: The key lacks the required scope or role. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: missing_scope required_scope: sessions:read RateLimited: description: >- Too many requests. Retry after the number of seconds in the `Retry-After` response header. headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer minimum: 1 required: true content: application/json: schema: $ref: '#/components/schemas/Error' example: error: type: rate_limited message: This API key exceeded its request-rate limit 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. ````