Agents

An agent is a Stripe-shaped resource: it owns cards, tokens, transactions, and exactly one policy at a time. Agents are typed for AI use — they carry a purpose, optional framework (openai-assistants, anthropic-sdk, langgraph, crewai), and optional capabilities so the dashboard and audit trail can describe what they’re for.

The agent model

Field	Description
`id`	`ag_*`
`name`	Display name
`policyId`	Exactly one policy, mutable but always present
`profile.purpose`	Required. Free text — describe what the agent does.
`profile.framework`	Optional — e.g. `langgraph`
`profile.capabilities`	Optional `string[]` — what the agent can do
`profile.description`	Optional longer description
`profile.department`	Optional cost-center tag
`profile.ownerContact`	Optional escalation contact
`status`	`active` · `suspended` · `archived`

Minimal create

The dashboard create drawer (and the documented happy path) is name + purpose + policyId. Other profile fields are optional, hidden behind an “Advanced” toggle.

curl -X POST https://api.getovra.com/agents \
  -H "Authorization: Bearer $OVRA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "name": "procurement-bot",
    "policyId": "po_default_...",
    "profile": { "purpose": "Buy office supplies under EUR 100" }
  }'

const agent = await ovra.agents.create({
  name: "procurement-bot",
  policyId: "po_default_...",
  profile: { purpose: "Buy office supplies under EUR 100" },
});

ovra_agent { action: "provision", name: "procurement-bot", policyId: "po_default_...", profile: { purpose: "..." } }

Lifecycle

Endpoint	Purpose
`POST /agents`	Create (idempotent)
`GET /agents/:id`	Read
`PATCH /agents/:id`	Update name / profile / status
`DELETE /agents/:id`	Archive (cascades over cards + tokens)
`POST /agents/:id/freeze` / `/unfreeze`	Pause / resume authorization
`POST /agents/:id/tokens`	Issue an agent-scoped token (`at_*`)

Agent tokens

Agents can hold their own scoped tokens (at_*). A token is bound to one agent, carries typed permissions, and may have an optional spend cap (via delegation).

curl -X POST https://api.getovra.com/agents/ag_.../tokens \
  -H "Authorization: Bearer $OVRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "production-runtime",
    "scopes": ["intents.write", "checkout.write"],
    "expiresInDays": 90
  }'

Use at_* tokens in your runtime instead of sharing your org-level sk_* key. Cross-agent reads with an at_* token return 403 E_AGENT_ISOLATION — strict isolation is one of the sacred invariants.

Signing keys (Phase 8 prep)

For each agent, an Ed25519 keypair is provisioned async. The public JWK is exposed at:

GET /.well-known/agent-jwks/{agent_id}

This is wiring for Visa Trusted Agent Protocol (RFC 9421 HTTP Message Signatures). No outbound signing is enabled in v1.2 — code lands when the first TAP-aware merchant requires it.

Webhooks

agent.created
agent.frozen
agent.unfrozen

Plan-tier limits

Plan	Agents
Free	1
Starter	5
Business	10
Enterprise	Unlimited

Surfaces

Surface	Capability
REST	`/agents`, `/agents/:id/tokens`
SDK	`ovra.agents.*`
MCP	`ovra_agent` (admin-side)
Dashboard	`/dashboard/agents`

Cards

Issue cards bound to an agent.

Policies

Define what an agent can spend.

Intents

The approval primitive every charge starts with.

Pay

How an agent actually pays.

Getting Started

The Six Pillars

Core Primitives

Payment Modes

Platform

The agent model

Minimal create

Lifecycle

Agent tokens

Signing keys (Phase 8 prep)

Webhooks

Plan-tier limits

Surfaces

Next

Cards

Policies

Intents

Pay

​The agent model

​Minimal create

​Lifecycle

​Agent tokens

​Signing keys (Phase 8 prep)

​Webhooks

​Plan-tier limits

​Surfaces

​Next

Cards

Policies

Intents

Pay

The agent model

Minimal create

Lifecycle

Agent tokens

Signing keys (Phase 8 prep)

Webhooks

Plan-tier limits

Surfaces

Next