Skip to main content

Operation approvals

What happened to an operation sent for approval by link. Two read-only tools, available to every connected client: they only inform — none of them approves, cancels or reopens an approval.

A destructive tool called by a client that cannot confirm in the chat answers approval_required with an approval.id and a URL. Show the URL to the user and do not call the tool again. Once the user says they chose Continue or Cancel, call operation_approvals_get with that approval.id — once, not in a loop.

Both tools see only your own approvals — the person behind the token — in the token's organization and the connection's workspace. They need no specific resource scope and no permission — the data is your own — but, unlike me, the token needs reach: any inbox/… scope or a bare all (otherwise INSUFFICIENT_SCOPE with details.required: ["inbox/all"]). The outcome (result, error) is the resource's data, though: it shows only when the token reaches that resource and you still hold its read permission; otherwise it is withheld and result_hidden is true.


operation_approvals_get​

Read · reach (any inbox/… or all) · no permission · active member · GET /operation-approvals/{id}

One approval, by the approval.id of the approval_required answer. Another person's approval, another organization's or an id that does not exist answers the same NOT_FOUND — the tool does not reveal that it exists.

ParameterTypeDescription
id requiredstring (uuid)The approval.id of the approval_required answer.
{
"data": {
"id": "2b0f8c1e-…",
"status": "executed",
"action": "webhooks_regenerate_secret",
"title": "Rotate the webhook signing secret",
"resource": "webhooks",
"operation": "regenerate_secret",
"requested_at": "2026-10-31T12:00:00.000Z",
"expires_at": "2026-10-31T12:15:00.000Z",
"decided_at": "2026-10-31T12:03:10.000Z",
"executed_at": "2026-10-31T12:03:10.400Z",
"error": null,
"result": { "data": { "id": "…", "signing_secret": "[redacted]" } },
"result_hidden": false
}
}
FieldMeaning
statuspending, approved (Continue was chosen and it is still running), executed, failed, declined (Cancel) or expired. A pending approval past expires_at is already answered expired.
actionThe tool that was asked for.
titleThe operation, as the approval screen names it, in the language of the request (Accept-Language; Portuguese by default, English or Spanish).
resource / operationWhat the operation acts on and what it does there.
requested_at / expires_at / decided_at / executed_atWhen it was asked for, until when the link was valid, when the person decided and when it ran.
error{ code, message } when failed — e.g. SUBJECT_CHANGED when the record changed after the screen was shown; null otherwise.
resultWhat the tool returned when executed, with every secret masked ([redacted]): a one-time secret is shown once, on the approval screen. null otherwise.

| result_hidden | true when this token cannot read the approval's resource (inbox/<resource> — e.g. inbox/webhooks for webhooks_regenerate_secret — or an access level that reaches it) — and, as on every read, you still hold the read permission of that resource (<resource>.show) in the organization. Otherwise result and error are null whatever happened. The other fields still show. |

The approval link, its token and the card the person saw are never returned.

operation_approvals_list​

Read · reach (any inbox/… or all) · no permission · active member · GET /operation-approvals

Your approvals in the workspace, newest first, with the same fields as operation_approvals_get. Page-based: { data, meta: { total, page, per_page, total_pages } }.

ParameterTypeDescription
statusstringOnly approvals in this status: pending, approved, executed, failed, declined or expired (a lapsed pending one counts as expired, not pending).
created_afterstringRequested at or after this ISO 8601 timestamp.
created_beforestringRequested at or before this ISO 8601 timestamp.
pageintegerPage number, default 1.
per_pageintegerPage size, default 25, max 100.