Authentication

Aly exposes three credential kinds. Which one you use depends on whether the caller is a browser, a long-lived integration, or a third-party agent that needs user consent.

Credential kinds

Kind	Prefix	Issued by	Where
API key	`aly_`	Workspace owner from Settings → API keys	MCP, UCP, A2A, REST merchant endpoints
OAuth token	`aly_oauth_`	OAuth 2.1 consent flow	Third-party agents acting on a user's behalf
Session JWT	`__convexAuthJWT` cookie	Sign-in from the dashboard	Browser UI only — rejected by agent surfaces

Session JWTs are explicitly rejected

MCP, UCP, A2A, and the REST merchant endpoints will refuse a session cookie even if you forward it manually. Agent surfaces require a bearer token whose lifetime, owner, and scope set are durable and revocable. This is a deliberate boundary.

API keys

Created in the dashboard, bound to a workspace, scope-gated, long-lived until revoked. Use these for your own integrations and CI jobs.

Send as Authorization: Bearer aly_... on every request.

1curl https://aly.store/api/storefront/v1/merchant/orders \2  -H "Authorization: Bearer aly_a8d9...e3c7"

Keys carry a workspace id (orgId), the issuing user id (for audit only), and a scope set. Authorization decisions are made against the workspace; user identity is recorded but not load-bearing.

OAuth 2.1

For shipping a multi-tenant agent that other workspaces install. The flow is the standard OAuth 2.1 Authorization Code with PKCE — dynamic client registration, consent screen, code exchange.

Discovery

1curl https://aly.store/.well-known/oauth-authorization-server

Returns RFC 8414 metadata: authorization_endpoint, token_endpoint, supported scopes, supported grant types, and the dynamic client registration endpoint.

Flow

Register your client (dynamic registration) and store the returned client_id and client_secret.
Redirect the user to /oauth/authorize with response_type=code, client_id, redirect_uri, scope, and a PKCE code_challenge.
User consents. We redirect back with code.
Exchange the code at /oauth/token for an aly_oauth_* access token (and refresh token, if requested).
Call any agent surface with Authorization: Bearer aly_oauth_....

Workspace scoping

OAuth tokens are scoped to the workspace the user consented from. If the same user belongs to multiple workspaces, you'll receive a separate token per workspace.

Scopes

Sixteen scopes cover the full agent surface. Both API keys and OAuth tokens enforce them identically.

Scope	Grants
`read:sites`	Read site config, theme, settings
`write:sites`	Update site config, publish/unpublish
`delete:sites`	Delete sites
`read:content`	Read products, collections, pages, CMS blocks
`write:content`	Mutate products, collections, pages, CMS blocks
`read:customers`	Read customers and customer groups
`write:customers`	Mutate customers and customer groups
`manage:voice`	Configure voice agents
`manage:domains`	Attach/detach custom domains
`manage:api_keys`	Mint and revoke API keys
`read:analytics`	Read site analytics + activity feed
`read:orders`	Read orders, fulfillment state, returns/exchanges
`write:orders`	Update order state, fulfill, refund
`read:media`	Read media assets
`write:media`	Upload, replace, delete media assets
`manage:workspace`	Workspace settings
`manage:team`	Invite and remove teammates

See Operator vs storefront scopes for the breakdown of which scopes are needed for hosted-storefront vs operator-mode integrations.

Rate limits

Two layers:

Pre-auth, per-IP — an in-memory bucket protects the bearer-verification path itself.
Post-auth, per-principal — durable, Convex-backed, counted against the workspace.

When you exceed a limit you'll get HTTP 429 with a Retry-After header. The exact ceilings adjust over time and are intentionally undocumented; budget for backoff.

Revocation

Revoke an API key from Settings → API keys. OAuth tokens can be revoked from the consent management page or by POSTing to the OAuth /revoke endpoint. Revocation is immediate — in-flight requests with the revoked token will fail on their next call.

Was this page helpful?