> ## 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.
# Import a local MCP OAuth credential
> Validates and imports a locally held OAuth credential for an existing MCP server. Temporary mode never stores or refreshes a refresh token. Transfer mode takes ownership of the supplied refresh-token chain. The access token is validated immediately; the refresh token is not exercised until the access token expires because testing it could rotate the local client's token chain. Token values are write-only and never returned.
Scope: `mcp:write`
## OpenAPI
````yaml /openapi.json post /v3/organizations/{orgId}/mcp-servers/{id}/oauth-import
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}/mcp-servers/{id}/oauth-import:
parameters:
- $ref: '#/components/parameters/orgId'
- name: id
description: The MCP server id.
in: path
required: true
schema:
type: string
post:
tags:
- MCP Servers
summary: Import a local MCP OAuth credential
description: >-
Validates and imports a locally held OAuth credential for an existing
MCP server. Temporary mode never stores or refreshes a refresh token.
Transfer mode takes ownership of the supplied refresh-token chain. The
access token is validated immediately; the refresh token is not
exercised until the access token expires because testing it could rotate
the local client's token chain. Token values are write-only and never
returned.
Scope: `mcp:write`
operationId: importMcpOAuthCredential
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/McpOAuthImportInput'
responses:
'200':
description: Credential imported and verified.
content:
application/json:
schema:
type: object
properties:
connected:
type: boolean
const: true
mode:
type: string
enum:
- temporary
- transfer
expires_at:
type: string
format: date-time
refresh_owned_by_reason:
type: boolean
refresh_tested:
type: boolean
const: false
description: >-
Always false. Testing an imported refresh token could
rotate or invalidate the local client's token chain.
required:
- connected
- mode
- expires_at
- refresh_owned_by_reason
- refresh_tested
'400':
$ref: '#/components/responses/BadRequest'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'409':
$ref: '#/components/responses/Conflict'
'422':
description: OAuth discovery or access-token verification failed.
security:
- araApiKey:
- mcp: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:
McpOAuthImportInput:
type: object
properties:
mode:
type: string
enum:
- temporary
- transfer
access_token:
type: string
maxLength: 65536
description: Write-only OAuth access token. Never returned.
refresh_token:
type: string
maxLength: 65536
description: Write-only. Transfer mode only.
expires_at:
type: string
format: date-time
scopes:
type: string
maxLength: 8192
source_application:
type: string
maxLength: 120
device_label:
type: string
maxLength: 120
replace_existing:
type: boolean
default: false
description: Required as true to replace an existing OAuth connection.
acknowledgement:
type: string
const: reason_owns_refresh_token
client:
type: object
properties:
client_id:
type: string
maxLength: 2048
client_secret:
type: string
maxLength: 16384
description: Write-only OAuth client secret. Never returned.
token_endpoint_auth_method:
type: string
enum:
- none
- client_secret_basic
- client_secret_post
required:
- mode
- access_token
- expires_at
- source_application
- device_label
description: >-
Imports a local OAuth credential for an existing HTTP MCP server.
Temporary mode stores only the access token until expiry. Transfer mode
also stores the refresh token and originating OAuth client, and requires
acknowledgement that Reason owns future refreshes.
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
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
Conflict:
description: The request conflicts with the current resource state.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: last_owner
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.
````