Skip to main content
EchoZero supports OAuth 2.1 authorization code with PKCE for clients that cannot safely store long-lived API keys - Claude connectors, ChatGPT apps, local CLIs, and directory integrations.

Endpoints

User consent is handled in the Dev Portal at devportal.echozero.app/mcp/oauth/authorize. Users approve from their saved portal session - do not ask them to copy JWTs from browser devtools.

PKCE parameters

Generate a code_verifier (43-128 random characters) and keep it secret until token exchange.
1

Redirect to authorize

Send the user to GET https://mcp.echozero.app/oauth/authorize with PKCE code_challenge, state, scope, and redirect_uri.
2

User approves in Dev Portal

EchoZero redirects to the Dev Portal consent page. If the user is not signed in, they authenticate first, then approve the requested scopes.
3

Receive authorization code

EchoZero redirects back to your redirect_uri with ?code=...&state=.... Verify state matches what you sent.
4

Exchange code for token

Response:
5

Call protected APIs

Send Authorization: Bearer <access_token> on REST and MCP requests.

Verify the token

After login, confirm the token is active:
For server-side validation without calling user-scoped routes:
It returns HTTP 201 (not 200) with the standard success envelope. For a valid token:
For an unknown or expired token, data is { "active": false }.

OAuth scopes

Scopes map to API key permissions. Request only what your integration needs. The single scope table, with the full list, is in Authentication overview. admin:* is not available via OAuth. The published directory manifests request the read: and write: scopes and do not include trades:execute.

Token lifetime and refresh

When the access token expires, re-run the PKCE consent flow or use a long-lived API key for headless servers. There is no offline_access or refresh grant at this time.

code_verifier requirements

43-128 characters from [A-Z], [a-z], [0-9], ., -, _, ~ (unreserved URI characters).

OAuth error responses

OAuth errors use the same envelope as the rest of the API, not the bare error / error_description fields from the OAuth spec. A generic OAuth library will not parse them. Match on the HTTP status and error.code.

MCP with OAuth

OAuth tokens work on MCP the same way as API keys:
  1. POST https://mcp.echozero.app/mcp with Authorization: Bearer <access_token> on every request, including initialize.
  2. Save the mcp-session-id response header from initialize.
  3. Send mcp-session-id: <session> on subsequent MCP calls (tools/list, tools/call, SSE stream, etc.).
MCP sessions are bound to the credential used at initialize. Switching API keys or OAuth tokens while reusing the same mcp-session-id returns 403 with JSON-RPC error code -32002.
See the MCP Server guide for a full initialize example.

Assistant setup

The ez CLI runs this PKCE flow for you with the echozero-cli client and wires up your assistant:
The skills pack (EchoZeroApp/skills) is not public yet.

Directory integrations

For ChatGPT, Claude, Gemini, and other assistant directories, use connector metadata from:
Per-platform manifests are individual files with the authorize URL, token URL, and recommended scope lists: index.json lists the others. There is no index page at /public/directory/{platform}/.