Skip to main content
POST
Ask a linked person to confirm an action

Authorizations

Authorization
string
header
required

Your secret server API key (bs_dev_… or bs_production_…) with Gates API access: the gates:write scope, granted in the Console under Settings → Developer Tools → API Keys. Without it every Gates API call answers gates_scope_required. The organization and environment always come from the key. Site keys are refused.

Body

application/json
request_id
string<uuid>
required

Your idempotency key for this request.

agent
string
required

The name of an agent your organization registered (Console → Trusted Agents) in this key's environment. Its display name heads the card.

Example:

"couchtour"

act
string
required

Your act string; starts with a live action key. Returned verbatim on the token.

Maximum string length: 128
Example:

"hold:3f1c…:9a0b1c2d3e4f5a6b"

partner_user_ref
string
required

Your reference for the person (the one you linked them with). The person must already be linked.

Maximum string length: 512
act_label
string

The card's title — what the person is confirming. Default: the action's name.

Maximum string length: 90
Example:

"Hold Summer ’26 tee · $40"

requested_by
string

Display only: who asked on the person's behalf, e.g. their assistant.

Maximum string length: 40
Example:

"Muse"

ttl_seconds
integer
default:600

How long the card waits for the person.

Required range: 60 <= x <= 86400

Response

Queued. NOTE: handler errors also arrive here (HTTP 200) as data.error — codes: invalid_key (401), gates_scope_required (403), action_invalid (400), action_not_found (404), action_off (404), agent_not_found (404), not_linked (409 — the person isn't linked to your company), request_id_reused (409).

data
object
required