> ## 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.

# Bootstrap a Mac SSH activation

> Starts the existing owner-scoped SSH attempt, returns a short-lived one-use reverse-SSH receipt, and runs the existing install/enrollment flow. The receipt must be consumed by the signed-in Mac worker; no bearer token is persisted.

<sub>Scope: `ssh:write`</sub>



## OpenAPI

````yaml /openapi.json post /v3/organizations/{orgId}/ssh-connections/{connectionId}/activate
openapi: 3.1.0
info:
  title: Reason 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,
    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: Account
    description: Verify a key and resolve the organization it belongs to.
  - name: Reasons
    description: >-
      Start here. A Reason is the long-running agent a person keeps: their main
      Reason and named ones, each with its own instructions, default model and
      repositories, conversation, Loops and Sessions. Give a Reason work by
      messaging it (sendReasonMessage) and read its replies with
      listReasonMessages.
  - name: Loops
    description: >-
      Standing work a Reason does, woken by a schedule or an event: a webhook, a
      GitHub event or a Slack message. Each wake opens or continues a Session of
      the Reason; webhook events that share a correlation key continue one
      Session.
  - name: Memory
    description: >-
      What Reasons remember across Sessions. Each Session starts by reading
      MEMORY.md (a short index) and the list of topic notes, and reads a note
      when its topic comes up. `personal` memory belongs to one person (the API
      key's owner) and only their Sessions read it; `team` memory belongs to the
      Workspace and every member's Sessions read it. memory:read lists, reads
      and searches; memory:write writes and deletes, in team memory only for a
      Workspace owner or admin.
  - name: Sessions
    description: >-
      A Session is one run of work inside a Reason: every Reason message and
      Loop wake runs in one, and createSession starts one directly for a single
      unattended task with a pass/fail outcome. Its transcript, events, result
      and pull request are read here.
  - name: Skills
    description: >-
      Reusable instruction bundles Reason selects semantically from their
      descriptions for matching agent tasks.
  - name: Workspace events
    description: >-
      Follow a whole workspace without polling each Session.
      streamWorkspaceChanges is a Server-Sent Events stream of view revisions:
      when a topic's revision moves, re-read that view. streamWorkspaceEvents is
      a resumable Server-Sent Events stream of what happened (a message added, a
      turn finished), replayed from Last-Event-ID for 7 days. Event webhooks
      POST the same events, signed (Standard Webhooks), to endpoints you
      register. sessions:read reads; webhooks also need automations:read /
      automations:write; the devices topic also needs devices:read.
  - name: Pages
    description: >-
      The HTML pages Reasons make: charts, dashboards and reports a person reads
      in the chat, opens full size, shares and finds in a Reason's Library. List
      and read the pages you may see, make one in a Reason's conversation or a
      Session, keep it current with updatePage (same id, link and share link, a
      new revision), share it and delete it. pages:read reads; pages:write
      writes. An Experiments feature (pages_api): elsewhere these return 403
      `pages_api_unavailable`.
  - name: Secrets
    description: >-
      Encrypted credentials injected into the agent's sandbox. Write-only:
      values can be set but never read back.
  - name: Attachments
    description: >-
      Files uploaded to the organization and shared with sessions, downloaded
      via short-lived signed URLs.
  - 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: 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: Devices
    description: >-
      Owned Mac and headless Device identity, bounded enrollment and root
      grants.
  - name: Cloud Access
    description: >-
      Keyless cloud sign-in for sessions: Reason's OIDC issuer facts and the
      AWS, Google Cloud and Azure connections a workspace trusts, including
      which run triggers each one signs in.
  - name: MCP Servers
    description: >-
      Org-level Model Context Protocol servers exposed to the agent. Secret
      values are write-only.
  - name: Plugins
    description: >-
      The plugin catalog (catalog connectors, custom MCP servers, native app
      connectors): install, browser OAuth sign-in, bundled skills and per-Reason
      settings. Never returns credentials.
  - name: Change Request Reviews
    description: >-
      Automated senior-engineer reviews posted on pull requests and merge
      requests.
  - 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: Roles
    description: Role assignments that govern what each member can do.
  - name: Settings
    description: 'Organization configuration: namespaced settings and the run tag policy.'
  - name: Provider credentials
    description: >-
      Configure Bring-Your-Own-Key (BYOK) API keys and subscription credentials
      for model providers. Secret values are write-only.
  - name: Feedback
    description: Report problems with the API or these docs to the Reason team.
  - name: Projects
    description: >-
      Deprecated: a project is a Reason with the same id. Use the Reasons
      operations; these remain for existing clients.
  - name: Automations
    description: >-
      The older form of Loops. Prefer the Loops under a Reason (listReasonLoops,
      createReasonLoop), which take every wake: schedule, webhook, GitHub,
      Slack. Use these for what Loops do not carry yet: a run's MCP and app
      tools, and automations not filed under a Reason.
paths:
  /v3/organizations/{orgId}/ssh-connections/{connectionId}/activate:
    parameters:
      - $ref: '#/components/parameters/orgId'
      - name: connectionId
        description: >-
          The exact connection id returned by the owning connection list, not a
          Device id.
        in: path
        required: true
        schema:
          type: string
          format: uuid
    post:
      tags:
        - Devices
      summary: Bootstrap a Mac SSH activation
      description: >-
        Starts the existing owner-scoped SSH attempt, returns a short-lived
        one-use reverse-SSH receipt, and runs the existing install/enrollment
        flow. The receipt must be consumed by the signed-in Mac worker; no
        bearer token is persisted.


        <sub>Scope: `ssh:write`</sub>
      operationId: activateSshConnection
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ActivateSshConnection'
      responses:
        '202':
          description: Short-lived Mac activation receipt.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SshConnectionActivation'
        '400':
          description: >-
            Invalid input; credential values and validation details are never
            reflected.
        '401':
          description: A valid public bearer credential is required.
        '403':
          description: Required scope or workspace access is missing.
        '404':
          description: Owned SSH connection not found.
        '409':
          description: >-
            Setup in progress, changed host key, quota, conflicting/expired
            idempotency key, or deleted connection.
        '413':
          description: Request exceeds 48 KiB.
        '429':
          description: Rate/cooldown limit; respect Retry-After.
        '503':
          description: >-
            Writes, headless admission, encrypted storage, audit or cleanup
            unavailable.
      security:
        - reasonApiKey:
            - ssh:write
components:
  parameters:
    orgId:
      name: orgId
      in: path
      required: true
      description: Organization id or slug. Resolve it with `GET /v3/self`.
      schema:
        type: string
  schemas:
    ActivateSshConnection:
      type: object
      properties:
        host_key_fingerprint:
          type: string
          pattern: ^SHA256:[A-Za-z0-9+/]{43}$
      required:
        - host_key_fingerprint
      additionalProperties: false
    SshConnectionActivation:
      type: object
      properties:
        connection:
          type: object
          properties:
            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: >-
                Connection id; pass it as `connectionId`. It is not the Device
                id.
            name:
              type: string
              description: Display name of the connection.
            host:
              type: string
              description: SSH host name or address.
            port:
              type: integer
              description: SSH port.
            username:
              type: string
              description: SSH user the worker is installed as.
            workspace_path:
              description: >-
                Remote folder Sessions work in; null uses the installer's
                default workspace.
              type:
                - string
                - 'null'
            auth_type:
              type: string
              enum:
                - password
                - private_key
              description: >-
                How Reason signs in: a password or a private key. The credential
                itself is never returned.
            host_key_fingerprint:
              description: >-
                The trusted SSH host key fingerprint; null until a host key is
                trusted.
              type:
                - string
                - 'null'
            pending_host_key_fingerprint:
              description: >-
                Host key fingerprint seen on connect and awaiting a trust
                decision; null otherwise.
              type:
                - string
                - 'null'
            device_id:
              description: >-
                The Device enrolled on the host, for targeting Sessions and
                `getDevice`; null until setup completes.
              type:
                - string
                - 'null'
            status:
              type: string
              enum:
                - saved
                - connecting
                - awaiting_host_key
                - connected
                - failed
              description: >-
                Setup progress: saved, connecting, awaiting a host-key decision,
                connected (setup completed, not current liveness), or failed.
            error_code:
              description: >-
                Why the last attempt failed, when `status` is failed; null
                otherwise.
              type:
                - string
                - 'null'
            created_at:
              type: string
              description: When the connection was saved.
            updated_at:
              type: string
              description: When the connection last changed.
          required:
            - id
            - name
            - host
            - port
            - username
            - workspace_path
            - auth_type
            - host_key_fingerprint
            - pending_host_key_fingerprint
            - device_id
            - status
            - error_code
            - created_at
            - updated_at
          additionalProperties: false
        operation_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)$
        receipt:
          type: object
          properties:
            protocol:
              type: number
              const: 1
            type:
              type: string
              const: ssh_install_relay
            authorityToken:
              type: string
              pattern: ^(?:reason|ara)_ssh_install_[A-Za-z0-9_-]{43}$
            authority:
              type: object
              properties:
                kind:
                  type: string
                  const: install_only
                authorityId:
                  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)$
                organizationId:
                  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)$
                userId:
                  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)$
                connectionId:
                  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)$
                attemptId:
                  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)$
                purpose:
                  type: string
                  const: install
                generation:
                  type: integer
                  exclusiveMinimum: 0
                transport:
                  type: string
                  const: reverse_ssh
                expiresAt:
                  type: string
                  format: date-time
                  pattern: >-
                    ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
                maxDurationMs:
                  type: number
                  const: 300000
                maxChannels:
                  type: number
                  const: 1
                allowTcpForwarding:
                  type: boolean
                  const: false
                allowPty:
                  type: boolean
                  const: false
              required:
                - kind
                - authorityId
                - organizationId
                - userId
                - connectionId
                - attemptId
                - purpose
                - generation
                - transport
                - expiresAt
                - maxDurationMs
                - maxChannels
                - allowTcpForwarding
                - allowPty
              additionalProperties: false
            relayUrl:
              type: string
              maxLength: 2048
            endpoint:
              type: object
              properties:
                host:
                  type: string
                  const: 127.0.0.1
                port:
                  type: number
                  const: 22
              required:
                - host
                - port
              additionalProperties: false
          required:
            - protocol
            - type
            - authorityToken
            - authority
            - relayUrl
            - endpoint
          additionalProperties: false
      required:
        - connection
        - operation_id
        - receipt
      additionalProperties: false
  securitySchemes:
    reasonApiKey:
      type: http
      scheme: bearer
      bearerFormat: 'reason_<hex> (legacy: ara_<hex>)'
      description: >-
        Your Reason API key from Settings › API keys. 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, devices:read, devices:write, devices:use,
        computers:read, computers:write, ssh:write, knowledge:read, memory:read,
        memory:write, skills:read, skills:write, pages:read, pages: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, network:read,
        network:write, automations:read, automations:write, agent_auth:read.
        devices:write, devices:use, computers:read, computers:write, ssh:write,
        network:read and network:write are opt-in, excluded from default keys.
        computers:read lists visible cloud and connected computers without
        waking them or granting execution access. devices:read discovers local
        Device targets; devices:use separately consents to local execution, so a
        discover-and-run local workflow needs both. devices:write manages
        enrollment and device grants; computers:write creates or deletes cloud
        computers; ssh:write manages retained SSH access. network:read reads the
        saved workspace network policy; network:write replaces custom allowed
        hosts and requires a current organization owner/admin. Legacy project
        PATCH requests containing network_allowed_hosts also require
        network:write plus their existing run scope and project management
        permission; saved project hosts do not affect current session egress.
        Only owners/admins can mint or manage keys with network:write; keys
        cannot grant themselves more authority. See /docs/network-policies for
        replacement semantics and runtime applicability. mcp:write manages MCP
        server configuration only; it does not authorize remote MCP-tool
        execution. sessions:read reads sessions, including the assistant,
        reasoning and tool activity in their events. sessions:debug is
        privileged: only for organization owners/admins, it expands session
        events to the full diagnostic projection (diagnostic event kinds, status
        text and raw event metadata).

````

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