Agent Capability Token

An Agent Capability Token (agt_…) lets an AI agent shop on a specific customer’s behalf — within boundaries the customer chose. It is the differentiator slice of Stella: every merchant gets agent traffic for free because /api/agent/* is just a different token type on the same backend.

What makes an agent token different

Aspect	Storefront token	Customer token	Agent token
Identifies	A merchant	A logged-in customer	An agent + a customer + a budget
Lifetime	Indefinite	~24h, renewable	Bounded by `expires_at`
Spending limit	None (merchant trust)	None (customer’s own card)	Hard `budget_cents` cap
Per-call audit	Mutations only	Mutations only	Every call, every endpoint
Auto-completes payment	n/a	If buyer confirms	Never — always returns a checkout URL the human must tap

Modeled on OAuth’s device flow because LLMs can’t open embedded browsers. The customer never sees the agent’s screen, and the agent never sees the customer’s password. Tokens never travel through the agent’s process before the customer has explicitly approved.

What an agent can do

/api/agent/* is a separate API surface optimized for LLM tool-use:

Endpoint	Effect
`GET /agent/catalog/search`	LLM-shape product search
`POST /agent/intent/find`	NL query → ranked candidates
`POST /agent/intent/find-and-add`	One-shot: find + create cart + add
`POST /agent/intent/find-and-buy`	One-shot: find + cart + checkout. Returns `checkout_url` for the human to tap. Stella never auto-pays.
`GET /agent/customer/me`	Customer profile (capability-token-aware)
`GET /agent/audit/me`	Agent’s own action history

Budget enforcement

Every mutation that allocates spend (find-and-buy, find-and-add if followed by checkout completion) checks:

if budget_used_cents + line_total_cents > budget_cents:
    return 402 PAYMENT_REQUIRED { "error": "budget_exceeded" }

budget_used_cents is incremented in the same transaction that finalizes the order (CheckoutFinalizer.consume_budget), so partial failures can’t double-spend.

Per-customer agent cap

A customer can have at most 10 active agent tokens at any time. The 11th consent/poll returns:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{ "error": "agent_cap_exceeded" }

The consent code stays approved — the customer can revoke an existing token and the next poll will succeed without re-issuing.

Audit trail

Every agent call writes to audit_events with:

actor_type = "agent"
actor_id = <agent_token_id>
action = <endpoint>
payload_hash
IP, UA, correlation ID

Customers see their full agent history at:

GET /api/storefront/customer/me/agents/{token_id}/audit

Merchants see aggregate per-agent activity in the dashboard’s My agents panel.

Revocation

Three paths, all instant:

Customer revokes from the dashboard’s customer-side My agents panel.
Customer revokes via API: DELETE /api/storefront/customer/me/agents/{id}.
Merchant revokes from the dashboard’s merchant-side panel (compliance / abuse cases).

The next agent call fails with 401.

Try it from the CLI

The reference smoke harness lives at examples/agent-cli/ in the agenticom repo. Seven subcommands cover the full flow:

agent-cli mint --scopes catalog:read,cart:write --budget 5000 --expires-in 1h
agent-cli poll
agent-cli search "black M tee"
agent-cli buy --product-id ...
agent-cli audit
agent-cli me
agent-cli revoke

Get Started

Authentication

Concepts

Agent Capability Token

What makes an agent token different

What an agent can do

Budget enforcement

Per-customer agent cap

Audit trail

Revocation

Try it from the CLI

​What makes an agent token different

​Consent flow (RFC 8628 Device Authorization)

​What an agent can do

​Budget enforcement

​Per-customer agent cap

​Audit trail

​Revocation

​Try it from the CLI

What makes an agent token different

Consent flow (RFC 8628 Device Authorization)

What an agent can do

Budget enforcement

Per-customer agent cap

Audit trail

Revocation

Try it from the CLI