Skip to main content
The authorize endpoint is the core of Veto. Call it before every tool execution to get an allow/deny decision. Veto evaluates all active policies for the agent and returns the result in a single synchronous response.

​
POST /v1/authorize

​
agent_id
string
required
UUID of the agent making the tool call.
​
tool_name
string
required
Name of the tool being invoked. Can be any string up to 255 characters — use a consistent naming convention across your application (e.g. file.write, send_email, db.query).
​
parameters
object
The parameters being passed to the tool. Used for parameter constraint evaluation in policies. The total serialized size of this object must not exceed 64 KB.Keys matching sensitive patterns (password, secret, token, key, credential, authorization, api_key, apiKey, access_token, refresh_token) are automatically redacted to "[REDACTED]" before being stored in the audit log.
curl -X POST https://api.veto.tools/v1/authorize \
  -H "Authorization: Bearer veto_..." \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "550e8400-e29b-41d4-a716-446655440000",
    "tool_name": "file.write",
    "parameters": { "path": "/home/user/doc.txt", "content": "Hello" }
  }'

​
Response

Returns an AuthorizationResult object.
​
allowed
boolean
required
true if the action is permitted, false otherwise. This is the primary field to branch on.
​
outcome
string
required
The authorization decision. One of "allowed" or "denied".
​
matchedPolicyId
string | null
required
UUID of the policy that produced this decision. null when the agent has no matching policy and the default-deny rule applies.
​
reason
string
required
Human-readable explanation of the decision. Useful for logging and surfacing context to users.
​
evaluatedAt
string
required
ISO 8601 timestamp of when the evaluation was performed.
{
  "allowed": true,
  "outcome": "allowed",
  "matchedPolicyId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "reason": "Allowed by policy \"Safe file operations\"",
  "evaluatedAt": "2026-01-15T10:30:00.000Z"
}

​
Agent status behavior

Veto checks the agent’s status before evaluating any policies:
  • active — normal policy evaluation proceeds.
  • suspended — all requests are immediately denied. No policies are evaluated.
  • revoked — all requests are immediately denied. No policies are evaluated.
To re-enable a suspended agent, update its status to "active" via PATCH /v1/agents/:id.

​
Default deny

If no enabled policy matches the tool call, Veto denies the request. Authorization requires an explicit allow — there is no implicit permission.

​
Audit logging

Every call to /v1/authorize is recorded in the audit log, including denied requests. If the audit log write fails (for example, due to a database error), the authorization decision is still returned — but the response will include: 
X-Veto-Audit: failed
This header signals a compliance gap: the decision was made but not recorded. Your integration should monitor for this header if audit trail completeness is a requirement.