API overview

AgentValet exposes two public API surfaces:

The agent API at https://api.agentvalet.ai/v1/*. Every call is signed by the agent’s RS256 key and brokered to the upstream SaaS platform via use_platform. This is what your agent invokes at runtime.
The owner API at https://api.agentvalet.ai/v1/approvals/* and via Supabase Edge Functions at https://<project>.supabase.co/functions/v1/*. These are the dashboard’s writes (approve, revoke, register, audit). Most operators won’t call these directly — they’re documented for enterprise integrators building custom dashboards.

For everything else (billing, OAuth callback, webhooks), there’s no public contract and we reserve the right to change the surface area without notice.

How agents call AgentValet

The recommended path is through the AgentValet MCP server, not by hitting /v1/actions directly. The MCP server handles JWT signing, endpoint discovery, error envelope parsing, and the long-poll for approval results. If you’re building inside Claude Code, Claude Desktop, Cursor, or another MCP-aware host, install the AgentValet MCP and call:


use_platform({
  platform: "slack",
  endpoint: "/api/chat.postMessage",
  method: "POST",
  scope: "slack:write",
  data: { channel: "#general", text: "Hello" }
})

The MCP server signs the request, sends it to POST /v1/actions, waits up to 50 seconds for owner approval if needed, and returns the upstream SaaS response. See Get started for installation.

If you need to call /v1/actions directly (e.g. building a custom MCP server, or integrating from a non-MCP host), see POST /v1/actions.

Authentication

All agent-facing endpoints require an RS256-signed JWT in the Authorization: Bearer <token> header. Claims:

Claim	Required	Notes
`agent_id`	yes	The agent’s UUID as shown in the dashboard
`owner_id`	yes	The owning organisation’s owner UUID
`iat`	yes	Issued-at timestamp (seconds)
`exp`	yes	Expiry — recommended ≤ 5 minutes from `iat`
`sub`	optional	If present, must match the agent’s `spiffe_id`

The JWT is verified against the public key registered for the agent (agents.public_key_pem). Mismatches return 401 invalid_signature and increment the circuit breaker.

The Paperclip company-key path is also supported for the Paperclip adapter — see the in-app guide on Paperclip key setup.

Owner-facing endpoints

Dashboard mutations use the owner’s Clerk JWT in the same Authorization: Bearer header. The proxy verifies the JWT against Clerk’s JWKS at https://clerk.agentvalet.ai/.well-known/jwks.json.

Rate limits

Endpoint group	Limit	Notes
`POST /v1/actions`	Per-agent, per-minute. See your plan.	Independent of upstream SaaS rate limits
`GET /v1/approvals/:id`	60/min per agent	Polling the result of a pending approval
`GET /v1/agents/me/pending-actions`	30/min per agent	24h pending + completed window
`POST /v1/approvals/passkeys/*`	10/min per IP	WebAuthn register / sign

Exceeding a limit returns 429 Too Many Requests with a Retry-After header.

Error envelope

All errors return a JSON body with this shape:


{
  "error": "scope_not_granted",
  "detail": "Agent does not have permission for slack:write",
  "correlation_id": "01HKZ7...",
  "report_hint": {
    "url": "https://api.agentvalet.ai/v1/agents/self/diagnostics",
    "suggested_payload": { "severity": "error", "code": "scope_not_granted" }
  }
}

error — a stable machine-readable identifier. Don’t substring; switch on it.
detail — human-readable, may change between releases.
correlation_id — Pino request id; quote this when filing a bug or emailing support.
report_hint — when present, your agent can POST the suggested payload to lodge a self-report tied back to this request. See report_self_diagnostic.

Endpoint reference

POST /v1/actions — proxy a call to a connected platform
Approvals API — owner-facing decide + agent-facing poll
Passkeys — WebAuthn enrolment + biometric approval
Agent pending actions — agent introspection