Skip to main content
EchoZero uses five credential types. Pick the one that matches your integration surface.

​
Decision table

I am building…CredentialWhere to get it
Server REST integrationAPI key (ez_live_) + optional secret (ezs_)Dev Portal
AI assistant / MCP clientOAuth bearer token or API keyOAuth flow or Dev Portal
Inbound agent webhookPer-agent secret (ezw_)Agent create / rotate response
Outbound execution callbackAgent webhookUrl signing secretAgent configuration
End-user session (rare for devs)User JWT from /api/auth/*Mobile/web app auth, not typical for bots

​
API key + REST HMAC

curl https://mcp.echozero.app/api/v1/users/me \
  -H "x-api-key: ez_live_..."
Optional HMAC for server-to-server hardening. See API keys + HMAC.

​
OAuth (assistants)

PKCE authorization code flow. Access tokens last 1 hour. There is no refresh token today: re-run the consent flow or use long-lived API keys for headless servers.

​
Inbound webhook HMAC

X-EZ-Timestamp: <unix_seconds>
X-EZ-Signature: HMAC_SHA256(ezw_secret, "${ts}.${canonicalJson}")
Different algorithm from REST HMAC. See Webhook security.

​
Scopes

OAuth and API keys share the same scope strings. Prefer the read:* / write:* form:
ScopeAccess
read:agents / write:agentsAgent CRUD
read:strategies / write:strategiesStrategy bots
read:wallet / write:walletWallet and virtual mode
read:tradesTrade history
trades:executeTrade execution (legacy alias; prefer write:wallet + agent flows)
read:earnEarnings and claims
read:ai / write:aiAI chat tools
admin:*Platform admin only (not available via OAuth)
Legacy aliases (agents:read, bots:write, etc.) still work.

​
MCP authentication

Send the same API key or OAuth token on every MCP request, including initialize. Sessions are credential-bound. See MCP Server.

​
Protected endpoints

All /api/v1/* routes (except public marketplace browse and inbound webhooks) require authentication. The API Reference playground may label auth as optional for try-it convenience; production calls must include credentials.