Skip to main content
POST
Import a local MCP OAuth credential

Authorizations

Authorization
string
header
required

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

Scopes

mcp:write

Path Parameters

orgId
string
required

Organization id or slug. Resolve it with GET /v3/self.

id
string
required

The record to act on: for a connection action, the connection's record id as listConnections lists it (an MCP server's id or a native installation's id, matching adapter); for an MCP server, id from listMcpServers; for a tool invocation, its id.

Body

application/json

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.

mode
enum<string>
required
Available options:
temporary,
transfer
access_token
string
required

Write-only OAuth access token. Never returned.

Maximum string length: 65536
expires_at
string<date-time>
required
source_application
string
required
Maximum string length: 120
device_label
string
required
Maximum string length: 120
refresh_token
string

Write-only. Transfer mode only.

Maximum string length: 65536
scopes
string
Maximum string length: 8192
replace_existing
boolean
default:false

Required as true to replace an existing OAuth connection.

acknowledgement
string
Allowed value: "reason_owns_refresh_token"
client
object

Response

Credential imported and verified.

connected
boolean
required
mode
enum<string>
required
Available options:
temporary,
transfer
expires_at
string<date-time>
required
refresh_owned_by_reason
boolean
required
refresh_tested
boolean
required

Always false. Testing an imported refresh token could rotate or invalidate the local client's token chain.