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

# List your SSH connections

> Lists only the caller's saved connections. No workspace/admin override or credential values.

<sub>Scope: `devices:read`</sub>



## OpenAPI

````yaml /openapi.json get /v3/organizations/{orgId}/ssh-connections
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:
    parameters:
      - $ref: '#/components/parameters/orgId'
    get:
      tags:
        - Devices
      summary: List your SSH connections
      description: >-
        Lists only the caller's saved connections. No workspace/admin override
        or credential values.


        <sub>Scope: `devices:read`</sub>
      operationId: listSshConnections
      responses:
        '200':
          description: Owned SSH connection metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SshConnections'
        '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:
            - devices:read
components:
  parameters:
    orgId:
      name: orgId
      in: path
      required: true
      description: Organization id or slug. Resolve it with `GET /v3/self`.
      schema:
        type: string
  schemas:
    SshConnections:
      type: object
      properties:
        connections:
          type: array
          items:
            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
          description: The caller's own saved SSH connections.
      required:
        - connections
      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.