> ## 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. # Create or replace a cloud access connection > Saves the workspace's one connection for a provider (`aws`, `gcp` or `azure`). Requires owner/admin. `config` is required and replaces the stored config; a changed config clears the last test. `enabled` and `allowed_triggers` keep their stored values when omitted; a new connection is enabled and allows `manual` and `api`. A connection signs in only runs whose trigger it allows: `manual` sessions started in the reason app; `api` sessions started with the api, the cli or by another session; `schedule` scheduled automations; `github_event` github mentions, issues and pull requests; `webhook` automation webhooks; `slack` slack mentions; `linear` linear issues. Scope: `org:write` ## OpenAPI ````yaml /openapi.json put /v3/organizations/{orgId}/cloud-access/{provider} 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: 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: 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/organizations/{orgId}/cloud-access/{provider}: parameters: - $ref: '#/components/parameters/orgId' - name: provider description: The cloud access provider. in: path required: true schema: type: string enum: - aws - gcp - azure put: tags: - Cloud Access summary: Create or replace a cloud access connection description: >- Saves the workspace's one connection for a provider (`aws`, `gcp` or `azure`). Requires owner/admin. `config` is required and replaces the stored config; a changed config clears the last test. `enabled` and `allowed_triggers` keep their stored values when omitted; a new connection is enabled and allows `manual` and `api`. A connection signs in only runs whose trigger it allows: `manual` sessions started in the reason app; `api` sessions started with the api, the cli or by another session; `schedule` scheduled automations; `github_event` github mentions, issues and pull requests; `webhook` automation webhooks; `slack` slack mentions; `linear` linear issues. Scope: `org:write` operationId: setCloudAccessConnection requestBody: required: true content: application/json: schema: type: object required: - config properties: config: type: object description: Provider identifiers, as in the connection. enabled: type: boolean allowed_triggers: type: array items: type: string enum: - manual - api - schedule - github_event - webhook - slack - linear minItems: 1 example: config: role_arn: arn:aws:iam::123456789012:role/reason region: us-east-1 allowed_triggers: - manual - api - schedule responses: '200': description: The saved connection. content: application/json: schema: type: object required: - provider - config - enabled - allowed_triggers - updated_at properties: provider: type: string enum: - aws - gcp - azure config: type: object description: >- Provider identifiers: aws `role_arn`, `region`; gcp `workload_identity_provider`, `service_account`, `project_id`; azure `tenant_id`, `client_id`, `subscription_id`. enabled: type: boolean allowed_triggers: type: array items: type: string enum: - manual - api - schedule - github_event - webhook - slack - linear description: Run triggers this connection signs in. updated_at: type: string format: date-time last_tested_at: type: - string - 'null' format: date-time last_test_ok: type: - boolean - 'null' last_test_message: type: - string - 'null' last_used_at: type: - string - 'null' format: date-time example: provider: aws config: role_arn: arn:aws:iam::123456789012:role/reason region: us-east-1 enabled: true allowed_triggers: - manual - api updated_at: '2026-10-16T09:00:00Z' last_tested_at: '2026-10-16T09:01:00Z' last_test_ok: true last_test_message: >- arn:aws:sts::123456789012:assumed-role/reason/reason-connection-test last_used_at: null '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' security: - reasonApiKey: - org:write components: parameters: orgId: name: orgId in: path required: true description: Organization id or slug. Resolve it with `GET /v3/self`. schema: type: string responses: BadRequest: description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: prompt_required 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 NotFound: description: Resource not found. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: session_not_found 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 schemas: 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. 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: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.