Approvals

When your policy says require_approval, the call waits until a person approves that exact request. Then it runs once, unchanged. This page explains who can decide, what they see, and what keeps an approval from being reused.

How a request waits#

The agent doesn't wait on the line. It gets Waiting for approval and an execution_id at once, and checks back later with get_execution_status. Nothing reaches your system until the request is approved.

Meanwhile the Gateway sends the request to the Control Plane: the agent, the person it acts for, the tool and its version, the policy version and rule, and the exact arguments with their SHA-256 fingerprint. The Control Plane doesn't take the Gateway's word for it. It checks the arguments again, works out the fingerprint itself, and evaluates the policy itself. Then it stores the request with its arguments encrypted.

The request appears under Approvals in that environment, in the Waiting list.

What the approver sees#

The approver sees the request as your system would receive it: the tool's title, each value the agent sent (with lists shown as tables), and the argument fingerprint. Under Exact arguments they can open the raw values. They also see who the agent acts for, which agent asked, which policy rule needs the approval, who decides, and when the request expires.

The arguments are only visible to approvers and auditors of that environment. Admins can see that a request exists, but not its arguments. Every time someone opens a request, it's recorded in the audit trail.

Separation of duties#

To decide a request, a person must be an Approver of the request's environment. Even then, these people can never decide it:

• the person the agent acts for
• the agent's owner (the admin who created it)
• whoever issued the token the agent used

So every approved call involves at least two people. If you open a request you can't decide, the console says why, for example "You own the agent that asked, so someone else must approve it."

The first decision counts. If two approvers decide at the same moment, one of them is told that someone else decided first.

Approval emails#

When a request needs a staff decision, every approver who could decide it gets an email. The email contains no arguments: only the tool's title, who the agent acts for, the agent, the environment, the expiry time and who decides, with a Review the request button. The values themselves stay behind the approver's sign-in.

Approvers can turn these emails off on their Account page, under "When a request waits for my approval". If an email can't be sent, Gatelion tries again after 1, 4, 9 and 16 minutes, then gives up. The request stays in Approvals either way.

Expiry#

A request that nobody decides expires 24 hours after it was made, unless an admin chose another time for the environment on Settings, under Requests wait for approval for (from 15 minutes to 7 days). A new time applies to requests made after it's saved. When a request expires, the agent gets Expired, with the code approval_expired, and the call never runs. If the agent still needs it, it must ask again.

After the approval: one final check#

An approval alone doesn't run the call. Once a request is approved, the Gateway asks the Control Plane for permission to run it, and the Control Plane checks everything again:

• The approval is still valid and hasn't expired.
• The agent, the person, the tool, the tool version, the argument fingerprint and the policy version are exactly the ones approved.
• The Gateway, the agent and the tool are still switched on.
• The person is still active. For a customer, their permission for the agent still stands.

Only then does the Control Plane issue a signed grant. It's valid for 60 seconds and bound to this one call and its argument fingerprint. The Gateway checks the grant and runs the call once.

If anything changed, there's no grant. Most changes cancel the request as soon as they're saved, before it gets this far (see below). The final check catches whatever else changed, for example a request whose arguments no longer match what was approved. The call then ends Failed with the reason as its code, such as tool_version_changed. A call that needs approval can never run without live contact with the Control Plane.

When a request is cancelled#

Some changes mean a request can never run as it was approved. Gatelion doesn't leave such a request waiting for a decision that can't help: it cancels it at once, when the change is saved.

This covers requests that are still waiting, and approved requests that haven't started running (no grant has been issued for them yet). A call that has already started running isn't affected.

• Approvers see the request as Cancelled in Approvals, with a sentence saying why, for example "The policy changed after the request. The agent has to ask again." Nobody can decide it any more.
• The agent gets Rejected with the reason as its code. A Gateway that hasn't been updated to the current version reports approval_rejected instead.
• A customer who opens the confirmation link sees No longer valid.
• The cancellation is recorded in the audit trail, and the execution's timeline shows Cancelled: it could no longer run.

If the agent still needs the call, it must ask again. The new request is checked, and approved if needed, under the current settings.

Stopping a Gateway with its Running switch doesn't cancel its requests; only retiring it does. While a Gateway is stopped, the final check doesn't let an approved request run through it.

Rejections#

An approver can Reject a request, with an optional comment. The agent gets Rejected, with the code approval_rejected, and the call never runs. A request Gatelion cancelled also ends rejected, with the reason as its code: see When a request is cancelled.

A request can also be rejected before anyone sees it: when the Control Plane refuses to create it. For example, the Gateway's policy may be older than the one just saved (policy_version_mismatch), or your organization may have reached its daily limit of approval requests (quota_exceeded). See Error codes.

When the customer decides#

For your customers' agents, a rule's Who confirms can be The customer (outside agents) or Both ("approvers": "customer" or "both" in JSON). Then the agent gets an approval_url with the pending status, and the customer confirms on a page that shows every value the agent sent, after signing in again with your login.

• With customer, only the customer can decide. Your approvers see the request but can't decide it, and no emails are sent.
• With both, the customer and one of your approvers must both approve, in either order.
• A rejection by either one rejects the request.

See What your customers see.

Related: Decide approvals for the steps in the console, and Executions and audit for what's recorded.

Still stuck? Contact support from the console.