Skip to main content
POST
Create or update a secret

Authorizations

Authorization
string
header
required

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.

Path Parameters

orgId
string
required

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

Body

application/json
name
string
required

Uppercase identifier, e.g. NPM_TOKEN.

value
string
required

The secret value. 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.

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.