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.
Browser consent flow
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
5
Call protected APIs
Send
Authorization: Bearer <access_token> on REST and MCP requests.Verify the token
After login, confirm the token is active: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 bareerror / 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:POST https://mcp.echozero.app/mcpwithAuthorization: Bearer <access_token>on every request, includinginitialize.- Save the
mcp-session-idresponse header frominitialize. - Send
mcp-session-id: <session>on subsequent MCP calls (tools/list,tools/call, SSE stream, etc.).
initialize example.
Assistant setup
Theez CLI runs this PKCE flow for you with the echozero-cli client and wires up your assistant:
EchoZeroApp/skills) is not public yet.
Directory integrations
For ChatGPT, Claude, Gemini, and other assistant directories, use connector metadata from:/public/directory/chatgpt/ai-plugin.json/public/directory/claude/connector.json/public/directory/gemini/extension.json
index.json lists the others. There is no index page at /public/directory/{platform}/.