OAuth PKCE for AI agents

Ettajer uses OAuth 2.0 authorization code with PKCE. Only code_challenge_method=S256 is accepted — plain challenges are rejected.

Authorization endpoint: GET /oauth/authorize (also available as /authorize). Required query params: client_id, redirect_uri (exact match to a registered URI), response_type=code, scope (space-separated), state (at least 8 characters), code_challenge, code_challenge_method=S256.

The merchant must be signed in and own a store. They review scopes and approve. Consent binds the grant to that one store for the life of the connection.

After redirect, exchange the code at POST /api/oauth/token (also /token) with grant_type=authorization_code, code, redirect_uri, client_id, client_secret, and code_verifier. Authorization codes are single-use and expire quickly.

The token response includes access_token (prefix eta_) and a rotating refresh_token. Send access tokens as Authorization: Bearer eta_… on /api/v1 and MCP.

Refresh with grant_type=refresh_token. Each refresh issues a new refresh token and invalidates the previous one — store the latest refresh token safely.

Revoke access with POST /api/oauth/revoke, or revoke the grant from the developer console under the app’s OAuth connections.

Discovery metadata: GET /.well-known/oauth-authorization-server (lists authorize/token endpoints and PKCE S256 support).

Security checklist: exact redirect match, PKCE S256, validate state, never log secrets, rotate secrets if leaked, prefer theme scopes without themes:publish for AI.

Examples and diagrams: /developers/oauth . Authentication overview: /developers/authentication .