Skip to main content
POST
cURL

Authorizations

Authorization
string
header
required

JWT Bearer token obtained from authentication. Pass as: Authorization: Bearer

Body

application/json

Ask the organization owner to provision a resource this agent cannot provision itself.

resource
enum<string>
required

Resource being requested: VAULT (encrypted secret storage for this agent) or PHONE_NUMBER (a provisioned number, Starter+ only).

Available options:
VAULT,
PHONE_NUMBER
reason
string
required

Why the agent needs this, shown verbatim to the owner. Required — an unexplained ask is not a decidable one.

Required string length: 1 - 500
agentId

Agent identifier. Optional when using an agent API key (resolved automatically); required when using a master key.

Pattern: ^[0-9a-z]+$
options
object

Resource-specific options; ignored for resources that take none

Response

OK

The created request, plus whether the owner notification actually went out

requestId
string
required

Unique provisioning request identifier

agentId
string
required

Agent the resource would belong to

agentName
string
required

Agent display name, so the owner knows who is asking

resource
enum<string>
required

Resource being requested: VAULT (encrypted secret storage for this agent), PHONE_NUMBER (a provisioned number, Starter+ only), or GENERIC (a master-gated operation the agent tried to perform; approving grants permission rather than provisioning anything).

Available options:
VAULT,
PHONE_NUMBER,
GENERIC
reason
string
required

The agent's stated justification

status
enum<string>
required

Lifecycle status: PENDING (awaiting the owner), APPROVED (resource provisioned), DECLINED (owner refused — soft, the agent may ask again), EXPIRED (7-day TTL elapsed unanswered), CANCELLED (withdrawn by the agent).

Available options:
PENDING,
APPROVED,
DECLINED,
EXPIRED,
CANCELLED
options
object | null
required

Resource-specific options, if any

permission
object | null
required

What the agent was refused, when this request records a permission rather than a resource

expiresAt
string<date-time>
required

When an unanswered request stops being actionable

decidedAt
string<date-time> | null
required

When the owner decided; null while PENDING

decidedNote
string | null
required

The owner's note, typically the reason for a decline — surfaced so a second attempt can address the objection instead of repeating the first

provisionedId
string | null
required

Id of what approval created (vault identity or phone identity); null unless APPROVED

createdAt
string<date-time>
required

When the agent asked

emailSent
boolean
required

Whether the owner was successfully emailed. False means the request is still live and visible in the console — the notification failed, not the request.