API reference

Approvals

Policies and approvals: action policies, approval requests, approve / deny, and grants.

Developer default policy

GET/v1/policy

If none has been set, rules is an empty array and updated_at is null (environments then use the built-in behavior; see PolicyRule).

Responses

200Developer default policy DefaultPolicy
401Missing, invalid or revoked key
500Internal error (details are recorded only in server logs)

Set the developer default policy

PUT/v1/policy

Replaces the whole policy. Used by every environment that does not have its own policy. For rule constraints see PutPolicyRequest.

Request body application/json · `PutPolicyRequest`

Field	Type	Description
`rules`required	`array of PolicyRule`

Responses

200Developer default policy DefaultPolicy
400Invalid parameters: validation failed, the body is not valid JSON, or the query string could not be parsed (all returned in the same JSON shape).
401Missing, invalid or revoked key
415Missing `Content-Type: application/json` (`unsupported_media_type`)
422The JSON does not match the schema: a missing field, a wrong type or enum value, or an unknown field (`invalid_body`)
500Internal error (details are recorded only in server logs)

Delete the developer default policy (revert to built-in behavior)

DELETE/v1/policy

Idempotent; returns 204 even if none was set.

Responses

204Deleted
401Missing, invalid or revoked key
500Internal error (details are recorded only in server logs)

Effective policy of an environment

GET/v1/environments/{id}/policy

If the environment has its own policy, that policy is used in full (source: environment); otherwise the developer default policy (developer); if neither exists, the built-in behavior (default, with empty rules). A destroyed environment gives 404.

Responses

200Effective policy of the environment EnvironmentPolicy
401Missing, invalid or revoked key
404Does not exist, or does not belong to this developer (`no such resource`); for a nonexistent route `message` is `no such route`
500Internal error (details are recorded only in server logs)

Set an environment's own policy

PUT/v1/environments/{id}/policy

Replaces the whole policy; from then on this environment no longer uses the developer default policy. The returned source is always environment.

Request body application/json · `PutPolicyRequest`

Field	Type	Description
`rules`required	`array of PolicyRule`

Responses

200Effective policy of the environment EnvironmentPolicy
400Invalid parameters: validation failed, the body is not valid JSON, or the query string could not be parsed (all returned in the same JSON shape).
401Missing, invalid or revoked key
404Does not exist, or does not belong to this developer (`no such resource`); for a nonexistent route `message` is `no such route`
415Missing `Content-Type: application/json` (`unsupported_media_type`)
422The JSON does not match the schema: a missing field, a wrong type or enum value, or an unknown field (`invalid_body`)
500Internal error (details are recorded only in server logs)

Delete an environment's own policy (revert to the developer default policy)

DELETE/v1/environments/{id}/policy

Idempotent; returns 204 even if none was set.

Responses

204Deleted
401Missing, invalid or revoked key
404Does not exist, or does not belong to this developer (`no such resource`); for a nonexistent route `message` is `no such route`
500Internal error (details are recorded only in server logs)

Check what the policy would decide for an action

POST/v1/environments/{id}/policy/check

Evaluates the environment's effective policy and the end user's grants for one connector and category, and explains the result. Read-only: it creates no approval request and does not use up a one-time grant. Useful for checking a policy before an Agent relies on it.

Request body application/json · `PolicyCheckRequest`

Field	Type	Description
`connector`required	`string`	A built-in connector (`gmail`, `calendar`, `slack`, `browser`) or `secret:NAME` for a developer secret.
`category`required	`ActionCategory`	Action category. `send`, `pay`, `delete` and `change_permission` are high-risk categories that rules cannot allow; they always require approval.
`task_id`	`string`	Task-scoped grants apply only when this matches.
`session_id`	`string`	Session-scoped grants apply only when this matches.

Responses

200The decision and why PolicyCheckResult
400Invalid parameters: validation failed, the body is not valid JSON, or the query string could not be parsed (all returned in the same JSON shape).
401Missing, invalid or revoked key
404Does not exist, or does not belong to this developer (`no such resource`); for a nonexistent route `message` is `no such route`
415Missing `Content-Type: application/json` (`unsupported_media_type`)
422The JSON does not match the schema: a missing field, a wrong type or enum value, or an unknown field (`invalid_body`)
500Internal error (details are recorded only in server logs)

List approval requests

GET/v1/approvals

Paginated in ascending order of created_at, id (same as the environments API). Requests past expires_at without a decision are settled as expired when read. status is not validated; an unknown status gives an empty list.

Parameters

Parameter	In	Type	Description
`environment_id`	query	`string`
`status`	query	`ApprovalState`
`limit`	query	`integer`	Items per page, default 50; values outside 1–200 are clamped into that range (no error).
`after`	query	`string`	The previous page's `next`.

Responses

200A page of approval requests ApprovalList
400Invalid parameters: validation failed, the body is not valid JSON, or the query string could not be parsed (all returned in the same JSON shape).
401Missing, invalid or revoked key
500Internal error (details are recorded only in server logs)

Get an approval request

GET/v1/approvals/{id}

Responses

200Approval request Approval
401Missing, invalid or revoked key
404Does not exist, or does not belong to this developer (`no such resource`); for a nonexistent route `message` is `no such route`
500Internal error (details are recorded only in server logs)

Approve or deny

POST/v1/approvals/{id}/decision

Two ways to authenticate; use exactly one:

API key (console, SDKs): Authorization: Bearer temper_sk_.... An invalid key gives 401 unauthorized.
Signature (your backend calling decision_url after receiving an approval.requested webhook): no Authorization header; instead send Temper-Signature, signing the raw request body with your webhook secret (whsec_), in the same format as webhooks. An invalid signature, a developer with no webhook configured (no secret), or a nonexistent approval request all give 401 invalid_signature.

Authentication happens before the body is parsed: a body that is not a valid decision gives 400 invalid_decision (not 422).

Approving "once" (once) lets only the pending request through and leaves no grant; every other scope leaves a grant (see GET /v1/grants).
404: does not exist or is not yours; 409 already_decided: already decided or expired; 400 missing_scope: an approval without scope, or an empty task / session id; 400 invalid_scope: the task / session id does not match the approval request's own task_id / session_id (if the request has none, that scope cannot be used), or until is not in the future; 403 scope_too_wide: wider than max_scope (once < task < session < until < permanent). On 400 / 403 the approval request stays pending, so you can correct the decision and try again.

Parameters

Parameter	In	Type	Description
`Temper-Signature`	header	`string`	Required when no API key is sent. `t=<unix seconds>,v1=<hex>`, where hex = HMAC-SHA256(webhook secret, ".").

Request body application/json · `DecisionRequest`

Field	Type	Description
`decision`required	`"approve" \| "deny"`
`scope`	`GrantScopeRequest`	Required when approving; ignored when denying.

Responses

200Status after the decision ApprovalDecisionStatus
400`invalid_decision` (invalid body), `missing_scope` or `invalid_scope`
401`unauthorized` (invalid API key) or `invalid_signature`
403`scope_too_wide`
404Does not exist, or does not belong to this developer (`no such resource`); for a nonexistent route `message` is `no such route`
409`already_decided` (including expired)
500Internal error (details are recorded only in server logs)

Active grants

GET/v1/grants

Grants that are not revoked and, if time-limited, not expired, in ascending order of creation time, at most 1000, not paginated.

Parameters

Parameter	In	Type	Description
`environment_id`	query	`string`

Responses

200Grants GrantList
400Invalid parameters: validation failed, the body is not valid JSON, or the query string could not be parsed (all returned in the same JSON shape).
401Missing, invalid or revoked key
500Internal error (details are recorded only in server logs)

Revoke a grant

DELETE/v1/grants/{id}

Idempotent: revoking an already revoked grant also returns 204. 404 if it does not exist or is not yours.

Responses

204Revoked
401Missing, invalid or revoked key
404Does not exist, or does not belong to this developer (`no such resource`); for a nonexistent route `message` is `no such route`
500Internal error (details are recorded only in server logs)

Approvals

#Developer default policy

Responses

#Set the developer default policy

Request body application/json · PutPolicyRequest

Responses

#Delete the developer default policy (revert to built-in behavior)

Responses

#Effective policy of an environment

Responses

#Set an environment's own policy

Request body application/json · PutPolicyRequest

Responses

#Delete an environment's own policy (revert to the developer default policy)

Responses

#Check what the policy would decide for an action

Request body application/json · PolicyCheckRequest

Responses

#List approval requests

Parameters

Responses

#Get an approval request

Responses

#Approve or deny

Parameters

Request body application/json · DecisionRequest

Responses

#Active grants

Parameters

Responses

#Revoke a grant

Responses

Developer default policy

Set the developer default policy

Request body application/json · `PutPolicyRequest`

Delete the developer default policy (revert to built-in behavior)

Effective policy of an environment

Set an environment's own policy

Request body application/json · `PutPolicyRequest`

Delete an environment's own policy (revert to the developer default policy)

Check what the policy would decide for an action

Request body application/json · `PolicyCheckRequest`

List approval requests

Get an approval request

Approve or deny

Request body application/json · `DecisionRequest`

Active grants

Revoke a grant