Skip to main content
POST
Create or update a secret

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
name
string
required

Environment variable name, e.g. NPM_TOKEN: letters, digits and underscores, starting with a letter, at most 128 characters. Upper and lower case are both accepted, but a new name may not differ only by case from one already stored in the same scope. Names Reason's runtime or the Session's shell own (PATH, HOME, USER, ...) are refused.

value
string
required

The secret value: not empty, not only whitespace, no NUL byte. Stored encrypted and never returned.

note
string

Optional usage guidance for agents and workspace members. Include the repository name when the secret is intended for one codebase. Omit to keep the stored note; send an empty string to clear it. Personal (user) secrets hold no note.

Maximum string length: 2000
scope
enum<string>
default:user
Available options:
organization,
user,
repo
repo
string

Deprecated context field for the repo compatibility scope. The value is stored workspace-wide.

provider
enum<string>

Deprecated provider context for the repo compatibility scope.

Available options:
github

Response

Secret stored.