Reference

The agent token

A JWT (typ: agent+jwt, EdDSA) that lasts 15 minutes.

{
  "iss": "https://api.trybage.com",
  "aud": "https://shop.example",
  "sub": "usr_5b1c9e",
  "name": "Alex Morgan",
  "act": { "sub": "agt_7a3d1f", "name": "Scout", "operator": "Northwind Labs" },
  "cnf": { "jkt": "<agent key thumbprint>", "jwk": { "kty": "OKP", "crv": "Ed25519", "x": "…" } },
  "scope": "browse cart",
  "iat": 1767225600,
  "exp": 1767226500,
  "jti": "tok_8d2e4f"
}

Claim	Meaning
sub, name	The person the agent acts for
act	The agent and the company that runs it
aud	The one site this token is for
cnf	The agent’s public key. Requests must be signed with it, so a stolen token is useless alone.
scope	What the person allowed
email, email_verified	Only with the email scope
test	Only for agents in test mode

Scopes

Each site picks what agents may ask for there: its own scopes, which it defines in the console, and any of Bage’s standard ones below. email is always allowed. GET /v1/sites?origin= lists a site’s scopes, its own with their title and description.

Scope	Lets the agent
email	Learn the person’s verified email, to match their account (OpenID standard)
browse	Look around signed in: prices, availability, order history pages
cart	Put things in the person’s cart
checkout	Place orders with the person’s saved details
read_account	Read profile, addresses and past orders
messages	Contact support or sellers as the person
bookings	Reserve tables, rooms or appointments

Errors

Errors are JSON: { "error": "code", "error_description": "…" }. The SDK throws them as BageError with the same code.

Code	When
authorization_pending	The person hasn’t answered yet; keep polling
access_denied	The person said no
expired_token	Nobody answered within 5 minutes
invalid_scope	A scope the site doesn’t allow, or a custom one it doesn’t have
invalid_client	Unknown client, or a bad, expired or reused client assertion
site_refused	The website blocked this agent, or only lets in agents it allowed
test_mode	A test agent asked someone outside its team and the test people
rate_limited	Too many requests
invalid_grant	A refresh token that is unknown, already used, expired or ended
unknown_user_id	An account link this agent doesn’t have, or the person unlinked it

Limits: an agent can ask a person who hasn’t set up Bage 5 times per 10 minutes, and at most 100 new people per hour. Every endpoint is in the API reference.