Skip to main content
POST
/
api
/
agent
/
consent
/
request
Post Consent Request
curl --request POST \
  --url https://api.example.com/api/agent/consent/request \
  --header 'Content-Type: application/json' \
  --header 'X-Site-ID: <x-site-id>' \
  --data '
{
  "agent_name": "<string>",
  "budget_cents": 5000000,
  "scopes": [
    "<string>"
  ],
  "allowed_categories": [
    "<string>"
  ],
  "token_ttl_seconds": 2592000
}
'
{
  "device_code": "<string>",
  "user_code": "<string>",
  "verification_uri": "<string>",
  "verification_uri_complete": "<string>",
  "expires_in": 123,
  "interval": 5
}

Documentation Index

Fetch the complete documentation index at: https://docs.stella-commerce.com/llms.txt

Use this file to discover all available pages before exploring further.

Headers

​
X-Site-ID
string
required

Body

application/json

Agent → Stella: start a consent flow.

The merchant is identified by the X-Site-ID header, NOT by a body field — same convention as /api/storefront/*. Multi-merchant agent tokens are out of scope for v1 (see PLAN §A2).

​
agent_name
string
required

Free-form agent identity displayed on the consent screen. The customer's approval is what makes the string trustworthy; Stella does not register or authenticate agent identities in v1.

Required string length: 1 - 120
​
budget_cents
integer
required

Hard spending cap in merchant-currency minor units. Decremented at order creation. Refunds do NOT restore.

Required range: 0 <= x <= 10000000
​
scopes
string[]

Coarse capability vocabulary the agent is requesting. Phase 6 v1: catalog:read, cart:write, checkout:create, customer:read. Unknown scopes are rejected at validation time (422) so a customer is never asked to approve a permission Stella doesn't honor.

Maximum array length: 16
​
allowed_categories
string[]

Optional category allowlist. Empty = any category. Match is against Product.product_type / Product.tags case-insensitively.

Maximum array length: 32
​
token_ttl_seconds
integer
default:2592000

Requested lifetime for the minted agt_ token, in seconds. Min 1 minute, max 90 days. Default 30 days.

Required range: 60 <= x <= 7776000

Response

Successful Response

Stella → agent: device-flow handshake response per RFC 8628 §3.2.

verification_uri_complete includes the user_code so the agent can render a single-tap link / QR code; verification_uri is the bare endpoint for clients that prefer to display the user_code separately.

​
device_code
string
required
​
user_code
string
required
​
verification_uri
string
required
​
verification_uri_complete
string
required
​
expires_in
integer
required

Seconds until the codes expire.

​
interval
integer
default:5

Minimum seconds between poll calls per RFC 8628 §3.2. Reserved for future slow_down cadence enforcement; Phase 6-B currently uses a per-IP token bucket instead.