How a call is governed
Every call an agent makes passes the same checks, in the same order, before anything reaches your system. This page follows one call: a purchasing agent asks your ERP to create a purchase order.
An agent asks
Gateway
What happens
inventory.list
Allowed: runs at once, result returned
purchase_orders.create
max_total 12,500
An approver decides, then it runs once
purchase_orders.cancel
No rule allows it: never reaches the system
The agent connects
The agent's MCP client connects to your Gateway's MCP address and sends two headers with every request:
Authorization: Bearer agt_…is the agent's token, issued in the console. It tells the Gateway which agent is calling.X-Gatelion-On-Behalf-Ofis the user id of the person the agent works for. An agent may act only for the people you chose when you created it.
The agent then asks which tools exist. It always sees get_execution_status, plus the enabled tools that your policy could let this agent run. A tool your policy never lets it run doesn't appear at all.
Your customers' agents connect differently: the customer signs in with your own login, and the access token names the customer, so no on-behalf-of header is needed. See Your customers' agents.
The Gateway checks the call
The agent calls erp.purchase_orders.create with max_total set to 12500. The Gateway checks the call in this order and stops at the first check that fails:
- The token. The token must be known, not expired or revoked, and its agent must be switched on. Otherwise the Gateway answers HTTP 401 and records nothing.
- The Gateway and your organization. A stopped Gateway denies every call (
gateway_disabled). So does an organization that has used its tool calls for the day (quota_exceeded). - The tool. The tool must be switched on, and your policy must have at least one rule that could let this agent run it. Otherwise the answer is
unknown_tool, the same answer as for a tool that doesn't exist. - The person. The on-behalf-of person must be one the agent may act for, and their account must be active (
on_behalf_of_not_allowed). - Rate limits. Each agent may make 60 calls a minute by default, and 60 a minute to each tool (
rate_limited). - The input. The Gateway puts the arguments into one exact form: Unicode text is normalized, spaces around text are trimmed, and Arabic-Indic or Persian digits in number fields become ASCII digits. It then checks them against the tool's input description and refuses unknown fields (
invalid_arguments, with a list ofinput_errors). The result gets a SHA-256 fingerprint. Two requests that mean the same thing get the same fingerprint and the same decision. - The policy. Rules are checked from top to bottom, and the first rule that matches decides: allow, deny or require approval. If no rule matches, the call is denied (
policy_denied, with the rule's id or "No rule matched"). - Freshness. The Gateway must have heard from the Control Plane recently enough: by default within the last hour for reads, and within 15 minutes for writes that need no approval (
stale_snapshot). Admins can change both times for each environment on Settings. Calls that need approval skip this check, because they can't run without live contact anyway.
Denied calls are recorded too, with the reason. The only calls not recorded are those refused before any check: a wrong token, a Gateway that has no configuration yet, or a Gateway already running as many calls as it allows at once (busy).
What happens next
Allowed
The Gateway records the call as being sent, calls your system once, and keeps only the output fields the tool defines. The agent gets succeeded and the result while it waits. Reads and writes that need no approval both work this way.
If the system answers with an error, the agent gets failed and the system's error code. If a write was sent but no reliable answer came back, the call ends unknown. The Gateway never sends a write twice on its own. See Executions and audit.
Needs approval
Your policy's rule for purchase orders over 1,000 says require_approval, so this call waits for a person.
- The agent gets an answer at once. The Gateway records the call as
pending_approvaland returns itsexecution_id. Nothing is sent to your ERP. - The Control Plane gets the request. The Gateway sends it the exact arguments and their fingerprint. The Control Plane checks them again, evaluates the policy itself, and stores the arguments encrypted. Approvers who can decide get an email.
- An approver decides. In Approvals, the approver sees the exact values the agent sent and their fingerprint, then clicks Approve this operation or Reject. The person the agent acts for, the agent's owner and whoever issued its token can't decide.
- The Control Plane checks again. The Gateway asks for decisions every 5 seconds. Once the request is approved, the Gateway asks the Control Plane for permission to run it. The Control Plane checks that the approval hasn't expired, and that the agent, the person, the tool version, the policy version and the fingerprint are still the ones approved. It also checks that the Gateway, the agent and the tool are still switched on, and that the person is still active.
- The call runs once. If everything holds, the Control Plane issues a signed grant. The grant is valid for 60 seconds and bound to this call and this argument fingerprint. The Gateway checks the signature and the binding, then sends the call to your ERP exactly once.
If the check in step 4 fails, the call doesn't run. It ends failed, with the reason as its code, for example tool_version_changed. A rejected request ends rejected, and a request nobody decided in time ends expired.
Some changes don't wait for step 4. Saving a new policy version, re-importing a changed tool, switching off the tool or the agent, removing the person's access, or retiring the Gateway cancels the request at once, whether it's still waiting or approved but not yet running. Approvers see it as Cancelled, and the agent gets rejected with the reason as its code, for example policy_changed. See Approvals.
Denied
A denied call is recorded with its code and never reaches your system. The agent gets denied, a code and a short message.
What the agent gets back
Every tool call returns the same JSON object, both as structured content and as text:
{
"status": "pending_approval",
"execution_id": "0199d7a2-5b1e-7c3a-9f40-2b8e6c1d4a77",
"result": null,
"code": null,
"message": null,
"approval_url": null,
"input_errors": null
}
| Status | Meaning |
|---|---|
| Succeeded | It ran. result holds the tool's output fields. |
| Waiting for approval | It waits for a person. Check again later with get_execution_status. |
| Approved | Approved and about to run, or running. |
| Denied | Refused before running. code says why. |
| Rejected | A person rejected it, the approval request was refused, or Gatelion cancelled it because something changed. It didn't run. code says why. |
| Expired | Nobody approved it in time. It didn't run. |
| Failed | It didn't succeed. code says why. |
| Unknown: reconcile | A write may or may not have happened. A person must check. |
For denied, failed, unknown, rejected and expired, the MCP result is also marked as an error. While a call is pending, the agent calls get_execution_status with the execution_id. It can only see its own calls. When a customer must confirm, approval_url holds the link to give them.
Where people see it
- Approvers see waiting requests under Approvals, and get an email when one needs them.
- Admins, approvers and auditors see every call under Executions & audit, with its status and a timeline: requested, approval required, approved, re-checked, sent, succeeded.
- Admins and auditors also see whether the audit trail is intact, at the top of the same page.
The Gateway reports what happened to the Control Plane every few seconds, so a call appears in the console shortly after it was made.
Next: follow the Quick start, or read more about Policies and Approvals.
Still stuck? Contact support from the console.