Agent keys
Create a key for each agent, limit it to some actions, give it an expiry, rotate it, and what an agent sees when it is refused.
An agent asks for approval with an agent key. Each key belongs to one workspace. A key can ask and read its own answers; it can never approve anything. Give every agent its own key, so the record shows which one asked and you can stop one without stopping the rest.
Creating a key
- Open Agents and name the key after the agent, such as mail-bot.
- Choose what it may ask for: any action, or only the actions you list.
- Choose when it stops working: never, after 30, 90 or 365 days, or on a date.
- Create it and copy the key at once. Only a hash is stored, so it is never shown again.
- Optionally, choose Send a test request. The page asks for approval with the new key, the way an agent would, and the request waits in the inbox for you to approve or deny. Nothing else happens, whatever you decide.
Only workspace owners can create keys. The same can be done over the API with a signed-in person’s session:
curl -X POST https://api.variantgate.com/v1/workspaces/WORKSPACE_ID/agent-keys \
-H 'authorization: Bearer YOUR_SESSION_TOKEN' \
-H 'content-type: application/json' \
-d '{
"name": "deploy-bot",
"scope": ["deploy.*", "refund.create"],
"expires_at": "2027-03-01T00:00:00Z"
}'Scopes: what a key may ask for
A scope lists the actions a key may ask about. It uses the same patterns as rules: an exact name such as refund.create, or a family such as deploy.*. A key without a scope may ask for any action.
- refund.create
- Only refund.create.
- deploy.*
- deploy.staging and deploy.production, but not deploy or deployx.
- *
- Any action, the same as no scope.
- A key’s scope lists at most 20 patterns.
- A
*may only come last.deploy.*.prodis refused. - Owners can change a key’s scope at any time under Agents, with Change. It applies from the key’s next request.
- A scope limits what the key may ask about. It approves nothing: a request in scope still needs a person or a rule to say yes.
What an agent sees when it is refused
A request for an action outside the key’s scope is refused at once. Nothing is stored, nobody is notified, and it does not count towards the plan. Over the API the agent gets:
HTTP/1.1 403 Forbidden
{
"error": {
"code": "action_out_of_scope",
"message": "this agent key may only ask for: deploy.*, refund.create"
}
}Over MCP, the request_approval tool answers with an error result whose structuredContent.error.code is action_out_of_scope. The SDKs raise a typed error, and the Claude Code and Codex hooks deny the tool call. Asking again will never work: an owner has to widen the scope, or the agent has to use another key.
import { OutOfScopeError } from "@variantgate/agent/errors";
try {
await client.ask({ action: "email.send", summary: "Send the March invoice" });
} catch (error) {
if (error instanceof OutOfScopeError) {
// Asking again will not help. Stop, and tell the person who runs you.
}
}from variantgate import OutOfScopeError
try:
client.ask("email.send", "Send the March invoice")
except OutOfScopeError:
# Asking again will not help. Stop, and tell the person who runs you.
raiseExpiry
A key can stop working on its own: after a number of days, or on a date up to five years ahead. From that moment it is refused exactly like a revoked key, with 401 unauthorized, on every call. Agents shows how long each key has left, such as “Expires in 12 days”, and “Expired” once it has.
Rotating a key
- Create a new key for the same agent, with the same scope.
- Put the new key where the agent reads it, and restart the agent.
- Check under Agents that the new key is being used, then revoke the old one. Revoking takes effect on its next call.
Requests keep the key they were asked with, so the record still shows which key asked after the old one is revoked.
Every change is logged
Creating, revoking, pausing and resuming a key, and changing its scope, each go into the workspace’s activity log, with who did it and when.
Scopes and expiry are checked by the current version of VariantGate. A server that runs an older version ignores them, which matters only to people who host VariantGate themselves while they upgrade.