Provide a secret request's value

Answers a pending secret request with its value, as the request’s card in the web app does, and continues the Session waiting on it. Only the member the request was issued to (for_user_id) may provide it. Requires secrets:write.

Where the value is stored follows the request: with secret_request.broker_hosts, as a workspace secret used only with those hosts; otherwise, when secret_request.reason_id is set, on that Reason, for everyone who uses it (its owner and managers save it), or, on a team Reason (secret_request.reason_team), kept private to you with keep_private: true (only your own messages to the Reason use it); otherwise as a workspace secret. A workspace secret needs a workspace owner or admin. The value is trimmed, must start with secret_request.value_prefix when one is set, and is never returned, logged or shown in the Session.

The Session continues once every secret its turn asked for is stored; until then the request stays pending. Retrying is safe: a retry’s value and keep_private are checked like a first call’s, but while a value that answers the request is already stored (a replace request counts only one stored after it was asked), nothing is written again and the sent value is not used; once the request is completed with its value stored, the request is returned unchanged. A request settled any other way returns 409 input_request_not_pending.

_{Scope: secrets:write}

POST /v3/organizations/{orgId}/sessions/{sessionId}/input-requests/{requestId}/secret

Provide a secret request's value

cURL

curl --request POST \
  --url https://api.reasonmachines.com/v3/organizations/{orgId}/sessions/{sessionId}/input-requests/{requestId}/secret \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "value": "sk_live_...",
  "keep_private": false
}
'

200

{
  "id": "<string>",
  "type": "question",
  "status": "pending",
  "session_id": "<string>",
  "asked_in_session_id": "<string>",
  "resumes_session_id": "<string>",
  "for_user_id": "<string>",
  "requires_role": "owner_or_admin",
  "origin": {
    "session_id": "<string>",
    "title": "<string>",
    "reason_name": "<string>"
  },
  "created_at": "<string>",
  "expires_at": "<string>",
  "reason": "<string>",
  "label": "<string>",
  "question": {
    "wait_for_answer": true,
    "questions": [
      {
        "header": "<string>",
        "question": "<string>",
        "multi_select": true,
        "options": [
          {
            "label": "<string>",
            "description": "<string>"
          }
        ]
      }
    ],
    "decision_timeout": {
      "assumption": "<string>",
      "at": "<string>"
    },
    "computer_auth": {
      "target": "cloud",
      "reason": "<string>"
    }
  },
  "secret_request": {
    "name": "<string>",
    "label": "<string>",
    "placeholder": "<string>",
    "value_prefix": "<string>",
    "replace": true,
    "broker_hosts": [
      "<string>"
    ],
    "reason_id": "<string>",
    "reason_name": "<string>",
    "reason_team": true
  },
  "network_hosts": {
    "hosts": [
      "<string>"
    ]
  },
  "permission_rules": {
    "changes": [
      "<string>"
    ]
  },
  "connector": {
    "provider": "<string>",
    "slug": "<string>",
    "server_id": "<string>",
    "plugin": "<string>",
    "description": "<string>",
    "icon": "<string>",
    "auth_type": "none",
    "auth_scheme": "basic",
    "fields": [
      {
        "name": "<string>",
        "label": "<string>",
        "description": "<string>",
        "required": true
      }
    ],
    "url": "<string>",
    "documentation_url": "<string>",
    "website_url": "<string>",
    "registry_name": "<string>",
    "registry_version": "<string>",
    "repository": "<string>",
    "configure_url": "<string>",
    "reconnect": true,
    "reason_id": "<string>",
    "reason_name": "<string>"
  },
  "actions": [
    "answer"
  ],
  "app_url": "<string>"
}

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

Path Parameters

orgId · string · required

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

sessionId · string · required

The session id, returned as session_id by createSession and listSessions.

requestId · string · required

An input request id returned as id by listSessionInputRequests or listInputRequests: a question's 64-character hex operation id, or a request card's UUID.

Pattern: ^(?:[0-9a-fA-F]{64}|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$

Body

application/json

value · string · required

The secret's value: not empty, not only whitespace, no NUL byte. Trimmed, then stored encrypted; never returned, logged or shown in the Session.

keep_private · boolean

Only for a request whose secret_request.reason_team is true: keep the value private to you on that Reason (only your own messages to it use it) instead of saving it for everyone who uses the Reason. Refused for any other request.

Response

200

application/json

The request after the value was provided: completed once the Session continued, pending while it waits for more of its turn's secrets.

id · string · required

The request's id: a question's 64-character hex operation id, or a request card's id (a UUID). A copy shown in a Reason's conversation has its source request's id.

type · enum<string> · required

Available options: question, secret, network_hosts, permission_rules, installed_connector, endpoint_connector, registry_connector, connector, native_connector, source_control, device_plugin, personal_connector_grant

status · enum<string> · required

pending: still waiting on a person. Questions: answered, moved_past (a person's later message in the Session settled it without answering it), cancelled, withdrawn (the agent took it back), timed_out (its wait or decision timeout ended it) or closed (any other end). network_hosts: allowed, declined, completed (every host was allowed elsewhere) or expired. permission_rules: applied, declined or expired. secret: completed (a value was saved and the Session resumed), declined (its member's Not now) or expired. Other connection types: completed (a connection resumed the Session), expired (after their receipt or 24 hours) or closed (the Session was cancelled or archived); their pending state is best effort, because the server records no answer for them.

Available options: pending, answered, moved_past, cancelled, withdrawn, timed_out, closed, allowed, declined, applied, completed, expired

session_id · string · required

The Session this copy is shown in.

asked_in_session_id · string · required

The Session whose agent asked.

resumes_session_id · string · required

The Session that continues once the request is completed.

for_user_id · string | null · required

The only member who may answer it (a question for one teammate, a personal connection grant, a secret card); null when anyone who can open the Session may.

requires_role · enum<string> | null · required

owner_or_admin: only a workspace owner or admin can complete it.

Available options: owner_or_admin

origin · object | null · required

Set on a copy of the request shown in a Reason's conversation (a request card copied there, or a question relayed to the member it is for); null on the asking Session's own request.

Show child attributes

created_at · string · required

expires_at · string | null · required

When the request's signed receipt ends, or for a secret or connection request without one the end of its 24-hour window; null for a question and for a network_hosts or permission_rules card without a receipt.

reason · string | null · required

Why the agent asks, in its words.

label · string · required

A short name for the request.

question · object | null · required

Show child attributes

secret_request · object | null · required

type secret: the secret the agent asks for (its name and how it is used), never a value.

Show child attributes

network_hosts · object | null · required

Show child attributes

permission_rules · object | null · required

Show child attributes

connector · object | null · required

Display fields of a connection request (every type but question, secret, network_hosts and permission_rules); a field a type does not use is null.

Show child attributes

actions · enum<string>[] · required

What this caller can do with it through the API now. Only actions an API route serves are listed: answer (a pending question this caller may answer; answerSessionInputRequest), approve and deny (a network_hosts or permission_rules request, for an owner or admin; approve also on a network_hosts request that reads completed, to record the answer), and cancel (the member's own secret request). Empty when the request is settled or must be completed in the web app: open app_url. A hint: every action checks again, so cancel on a secret request whose Session has moved on since it was asked returns 409 input_request_not_waiting.

Available options: answer, approve, deny, secret, cancel

app_url · string · required

The Session in the web app, where every request can be completed.