Skip to main content
POST
Create a local onboarding import handoff

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, 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, network:read, network:write, automations:read, automations:write, agent_auth:read. network:read and network:write are opt-in, excluded from default keys. 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).

Path Parameters

orgId
string
required

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

Body

application/json
env_file_count
integer
required

Number of environment files the local scan read; shown as context to the person approving the import.

Required range: 0 <= x <= 10000
project_count
integer
required

Number of projects the local scan covered; shown as context to the person approving the import.

Required range: 0 <= x <= 10000
detected_secrets
object[]

The secrets the scan found, by name and source, for the person to approve in the browser before any value leaves the CLI. Omitted means none were found.

Maximum array length: 500
imported_secret_count
integer

Sent only by older CLIs: secrets they imported before approval existed. Current clients omit it and send detected_secrets.

Required range: 0 <= x <= 10000

Response

A short-lived opaque browser handoff.

handoff
string
required

Opaque, short-lived token for this handoff; pass it as handoff to getOnboardingImportDecision and completeOnboardingImport.