Agent Auth

The Commerce API implements Better Auth Agent Auth on top of the same OpenAPI contract documented at Commerce API.

AI agents can discover, register, request capabilities, and call commerce operations with delegated user authority.

What the merchant decidesCopy Anchor Link

With Agent Auth, an AI agent starts with nothing until you approve it for your store. After that it keeps the public catalog, and anything else needs your approval. You see every capability the agent asks for and approve or deny the request as a whole. Approved access ends after an hour idle, or 24 hours at most. Then the agent asks again.

An API key isn't Agent Auth: anything holding an admin key can do what the key allows, without asking.

Agent Auth is coming with Grow. Free keys reach the 21 storefront tools.

DiscoveryCopy Anchor Link

Agents load the provider configuration from:

GET https://<api-host>/.well-known/agent-configuration

Response includes:

{
  "version": "1.0-draft",
  "provider_name": "Prood Commerce API",
  "description": "Multi-tenant commerce HTTP API. ...",
  "issuer": "http://localhost:3005/api/auth",
  "default_location": "http://localhost:3005/api/auth/capability/execute",
  "algorithms": ["Ed25519"],
  "modes": ["delegated", "autonomous"],
  "approval_methods": ["ciba", "device_authorization"],
  "endpoints": {
    "register": "http://localhost:3005/api/auth/agent/register",
    "capabilities": "http://localhost:3005/api/auth/capability/list",
    "describe_capability": "http://localhost:3005/api/auth/capability/describe",
    "execute": "http://localhost:3005/api/auth/capability/execute",
    "request_capability": "http://localhost:3005/api/auth/agent/request-capability",
    "status": "http://localhost:3005/api/auth/agent/status",
    "reactivate": "http://localhost:3005/api/auth/agent/reactivate",
    "revoke": "http://localhost:3005/api/auth/agent/revoke",
    "revoke_host": "http://localhost:3005/api/auth/host/revoke",
    "rotate_key": "http://localhost:3005/api/auth/agent/rotate-key",
    "rotate_host_key": "http://localhost:3005/api/auth/host/rotate-key",
    "introspect": "http://localhost:3005/api/auth/agent/introspect"
  }
}

Better Auth routes (registration, capability execute, device approval) are mounted at /api/auth/* on the API app (port 3005 in local dev).

Capabilities from OpenAPICopy Anchor Link

Every REST operation with an operationId in the OpenAPI spec becomes an agent capability:

An agent starts with nothing it can use. resolveAgentAccess refuses an agent with no store: one with no user behind it, or one whose user has several stores and hasn't approved it for one. Once the agent has a store it keeps the public catalog reads (listProducts, getProduct, getProductBySlug, listCategories, getStore, listCountries), the default grants for an agent host. Everything else, including other GET operations and every admin* operation, requires approval on the dashboard's device authorization page. All the capabilities in a request are approved or denied together. Only store owners and admins can approve a request that includes an admin* capability. Approving also binds the agent to the active store. On a Free store, Agent Auth is refused.

When the session ends, after an hour idle (agentSessionTTL: 3600) or 24 hours at most (agentMaxLifetime: 86400), it reactivates with the catalog defaults only, and the agent has to ask again.

Agent registration flowCopy Anchor Link

Calling the REST API directlyCopy Anchor Link

When an agent calls /v1/* with an Authorization: Bearer agent JWT:

1. API validates the JWT signature and expiry
2. Resolves the store: the one the agent was approved for, or the user's only store. A user with several stores must approve the agent for one
3. Checks the agent holds the capability for this exact operation. Holding one admin* capability doesn't unlock other admin routes
4. Executes the operation scoped to that store

curl -H "Authorization: Bearer eyJ..." \
  "https://api.prood.com/v1/products?perPage=5"

OpenAPI proxy executionCopy Anchor Link

When capabilities run through the default execute endpoint, the plugin proxies HTTP to the public API base URL:

Required environment variablesCopy Anchor Link

Database tablesCopy Anchor Link

The Agent Auth tables are defined in packages/auth/src/schema.ts and created by pnpm db:migrate:

Security considerationsCopy Anchor Link

• Agents operate with delegated user authority — they can only access data the approving user can access
• An agent can do nothing until it's approved for a store. After that, everything past the six public catalog capabilities needs explicit approval on the device authorization page
• Agent JWTs are short-lived and scoped to granted capabilities. Access ends after an hour idle, or 24 hours at most
• Tenant isolation applies — agents cannot cross organization boundaries
• Proxied capability execution requires agent metadata with organizationId and a matching key in AGENT_PROXY_API_KEYS_BY_ORG

Example: agent shopping assistantCopy Anchor Link

An AI shopping assistant agent might request these capabilities:

The merchant sees all five on the device authorization page and approves or denies the request as a whole. The two catalog reads were already granted, so the agent cannot start a cart or place an order without that approval.

Related pagesCopy Anchor Link