Security
Keep execution credentials in the runtime. Let Gate govern whether a proposed tool call may cross the execution boundary.
Security boundary
Your runtime owns execution. Provider keys, database credentials, tool functions, retries, and business logic stay in your application. Gate receives the proposed tool name, arguments, and the evidence you intentionally send for policy and review.
Key handling
| Practice | Guidance |
|---|---|
| Use server-side secrets | Store the sg_ agent key in environment variables, platform credentials, or a secrets manager. |
| Never expose keys to browsers | Agent API calls belong in the runtime, backend, worker, or trusted automation environment. |
| Separate environments | Use different Gate URLs and agent keys for development, staging, and production. |
| Rotate keys deliberately | Rotating an agent key invalidates signed approval tokens bound to the prior key context. |
Signed approval tokens
When signed approvals are enabled, an approved decision may deliver a one-time approval_token. Gate stores the raw token only for delivery and retains a hash/binding record for validation.
| Property | Behavior |
|---|---|
| Single use | Validation consumes the token so it cannot authorize execution twice. |
| Expiry bound | Expired tokens return {"valid":false,"reason":"expired"}. |
| Context bound | The approval is bound to tenant, agent, tool, exact review thread, current API-key hash, and expiry. |
| Delivered once | The raw token may appear only on the first successful approved-decision read. |
| Reusable task IDs | Validation uses the exact token binding, so later review threads under the same task ID do not invalidate an older still-valid token. |
If your runtime requires signed approval proof, an approved status without a token is not executable. Fail closed.
Validate before execution
POST /api/agent/approvals/validate
Authorization: Bearer sg_...
Content-Type: application/json
{
"task_id": "task-123",
"signature": "APPROVAL_TOKEN"
}Token failures such as invalid, expired, used, malformed, or missing inputs can be represented inside an HTTP 200 JSON response. Always inspect valid. Never treat a 2xx status by itself as approval.
Webhook verification
Decision webhooks are separate from Agent API authentication. Verify X-Guard-Signature against the exact raw request body with HMAC-SHA256.
X-Guard-Signature: sha256=<hex-hmac>
HMAC-SHA256(webhook_secret, exact_raw_request_body)Webhook destinations must use HTTPS. Gate rejects localhost, loopback, common private ranges, link-local destinations, and unsafe redirect targets.
Data minimization
Send enough context for policy and review, but avoid secrets, raw credentials, or full private documents when a summary, diff, selected fields, or fingerprint is enough. Tool execution does not require Gate to hold the external service credential.
Fail closed at the wrapper
The runtime should execute only on allow or a valid approved result. Unknown statuses, API errors, missing required proof, invalid tokens, and timeouts must not fall through to tool execution.