Skip to main content

​
POST /v1/authorize

The core authorization check. Call this endpoint before every tool execution in your agent. Veto evaluates all active policies for the agent and returns an allow/deny/escalate decision.

​
Request body

​
agent_id
string
required
UUID of the agent making the tool call.
​
tool_name
string
required
Name of the tool being called. Supports dot-notation namespacing (e.g., file.write, db.query).
​
parameters
object
Key-value pairs of the tool’s input parameters. Pass all parameters so that parameter_constraint rules are evaluated correctly.

​
Response

​
allowed
boolean
required
true if the action is authorized. Check this field before proceeding with tool execution.
​
outcome
string
required
Authorization decision. One of "allowed", "denied", or "escalated".
​
matchedPolicyId
string | null
required
ID of the policy that produced this decision. null if no policy matched and the default-deny rule applied.
​
reason
string
required
Human-readable explanation of the decision (e.g., "Tool allowed by policy 'production-safeguards'" or "No matching policy — default deny").
​
evaluatedAt
string
required
ISO 8601 timestamp of when the evaluation ran.
This endpoint returns 200 even when the action is denied. Always inspect the allowed field before executing the tool. HTTP errors (401, 500) indicate authentication or server failures, not authorization decisions.
Always pass parameters even if the tool takes no arguments. Omitting it causes parameter_constraint rules to be skipped.
curl --request POST \
  --url https://api.veto.tools/v1/authorize \
  --header 'Authorization: Bearer veto_your_api_key' \
  --header 'Content-Type: application/json' \
  --data '{
    "agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "tool_name": "file.write",
    "parameters": {
      "path": "/home/user/doc.txt",
      "content": "Hello"
    }
  }'

{
  "allowed": true,
  "outcome": "allowed",
  "matchedPolicyId": "p9f1a2b3-c4d5-6789-efab-012345678901",
  "reason": "Tool allowed by policy 'production-safeguards'",
  "evaluatedAt": "2024-11-15T14:23:01.456Z"
}