> ## 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.
# Start provider sign-in
> Starts the provider's interactive flow. Follow next_action and poll until terminal. Codex and Radius default to device-code authentication; other interactive flows may require pasting a callback URL from the user's browser. Copilot supports github.com accounts only; answer its Enterprise-domain prompt with an empty string. Starting again cancels only this user's previous login. Requires a workspace-bound user OAuth grant with org:write and owner/admin membership. API keys and browser sessions are not accepted. Login challenges are private to the initiating user. Sessions expire after ten minutes and are process-local: requests must reach the same API instance; after a restart or a 404, start a new login. Provider device codes may expire sooner. Never share login URLs or codes.
Scope: `org:write`
## OpenAPI
````yaml /openapi.json post /v3/organizations/{orgId}/provider-credentials/{providerId}/oauth/logins
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.ai
security:
- araApiKey: []
tags:
- name: Devices
description: >-
Owned Mac and headless Device identity, bounded enrollment and root
grants.
- 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/organizations/{orgId}/provider-credentials/{providerId}/oauth/logins:
parameters:
- $ref: '#/components/parameters/orgId'
- name: providerId
description: The provider identifier (e.g. openai, anthropic, google, deepseek).
in: path
required: true
schema:
type: string
post:
tags:
- Provider credentials
summary: Start provider sign-in
description: >-
Starts the provider's interactive flow. Follow next_action and poll
until terminal. Codex and Radius default to device-code authentication;
other interactive flows may require pasting a callback URL from the
user's browser. Copilot supports github.com accounts only; answer its
Enterprise-domain prompt with an empty string. Starting again cancels
only this user's previous login. Requires a workspace-bound user OAuth
grant with org:write and owner/admin membership. API keys and browser
sessions are not accepted. Login challenges are private to the
initiating user. Sessions expire after ten minutes and are
process-local: requests must reach the same API instance; after a
restart or a 404, start a new login. Provider device codes may expire
sooner. Never share login URLs or codes.
Scope: `org:write`
operationId: startProviderOAuthLogin
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/StartProviderOAuthLogin'
responses:
'202':
description: Sign-in started.
content:
application/json:
schema:
$ref: '#/components/schemas/ProviderOAuthLoginResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
description: Provider or login not found, expired, or not owned by this user.
'409':
description: Another login is using this provider. Retry later.
'503':
description: Credential storage or sign-in is unavailable.
security:
- araUserOAuth:
- 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
schemas:
StartProviderOAuthLogin:
type: object
properties:
method:
type: string
enum:
- interactive
- browser
- device_code
description: >-
Use a method advertised by the catalog. Defaults to device_code for
Codex and Radius, and interactive for other enabled providers.
account_key:
type: string
minLength: 1
maxLength: 512
description: >-
An existing OAuth account to reconnect. Omit to connect the
provider-identified Codex account; other enabled providers replace
their single default connection.
ProviderOAuthLoginResponse:
type: object
properties:
login:
type: object
properties:
login_id:
type: string
provider_id:
type: string
status:
type: string
enum:
- pending
- succeeded
- failed
- cancelled
expires_at:
type: string
format: date-time
description: Deadline for completing this login.
error:
type:
- string
- 'null'
events:
type: array
items:
oneOf:
- type: object
properties:
type:
type: string
const: info
message:
type: string
links:
type: array
items:
type: object
properties:
url:
type: string
label:
type: string
required:
- url
required:
- type
- message
- type: object
properties:
type:
type: string
const: auth_url
url:
type: string
instructions:
type: string
required:
- type
- url
- type: object
properties:
type:
type: string
const: device_code
user_code:
type: string
verification_uri:
type: string
interval_seconds:
type: number
expires_in_seconds:
type: number
required:
- type
- user_code
- verification_uri
- type: object
properties:
type:
type: string
const: progress
message:
type: string
required:
- type
- message
prompt:
type:
- object
- 'null'
properties:
id:
type: integer
exclusiveMinimum: 0
type:
type: string
enum:
- text
- secret
- select
- manual_code
message:
type: string
placeholder:
type: string
options:
type: array
items:
type: object
properties:
id:
type: string
label:
type: string
description:
type: string
required:
- id
- label
required:
- id
- type
- message
next_action:
oneOf:
- type: object
properties:
type:
type: string
const: prompt
prompt:
type: object
properties:
id:
type: integer
exclusiveMinimum: 0
type:
type: string
enum:
- text
- secret
- select
- manual_code
message:
type: string
placeholder:
type: string
options:
type: array
items:
type: object
properties:
id:
type: string
label:
type: string
description:
type: string
required:
- id
- label
required:
- id
- type
- message
authorization_url:
type: string
required:
- type
- prompt
- type: object
properties:
type:
type: string
const: authorize
url:
type: string
instructions:
type: string
required:
- type
- url
- type: object
properties:
type:
type: string
const: device_code
user_code:
type: string
verification_uri:
type: string
poll_after_seconds:
type: number
required:
- type
- user_code
- verification_uri
- poll_after_seconds
- type: object
properties:
type:
type: string
const: wait
poll_after_seconds:
type: number
required:
- type
- poll_after_seconds
- type: object
properties:
type:
type: string
const: complete
required:
- type
- type: object
properties:
type:
type: string
const: failed
message:
type: string
required:
- type
- message
- type: object
properties:
type:
type: string
const: cancelled
required:
- type
required:
- login_id
- provider_id
- status
- expires_at
- error
- events
- prompt
- next_action
required:
- login
Error:
type: object
properties:
error:
type: string
message:
type: string
required_scope:
type: string
description: >-
The capability required when the request was denied for a missing
scope.
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: unauthorized
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
securitySchemes:
araApiKey:
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.
araUserOAuth:
type: http
scheme: bearer
description: >-
A workspace-bound human user OAuth grant with org:write scope. The user
must be an organization owner/admin. API keys and browser sessions are
not accepted.
````