Decision table
| I am building… | Credential | Where to get it |
|---|---|---|
| Server REST integration | API key (ez_live_) + optional secret (ezs_) | Dev Portal |
| AI assistant / MCP client | OAuth bearer token or API key | OAuth flow or Dev Portal |
| Inbound agent webhook | Per-agent secret (ezw_) | Agent create / rotate response |
| Outbound execution callback | Agent webhookUrl signing secret | Agent configuration |
| End-user session (rare for devs) | User JWT from /api/auth/* | Mobile/web app auth, not typical for bots |
API key + REST 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
Scopes
OAuth and API keys share the same scope strings. Prefer theread:* / write:* form:
| Scope | Access |
|---|---|
read:agents / write:agents | Agent CRUD |
read:strategies / write:strategies | Strategy bots |
read:wallet / write:wallet | Wallet and virtual mode |
read:trades | Trade history |
trades:execute | Trade execution (legacy alias; prefer write:wallet + agent flows) |
read:earn | Earnings and claims |
read:ai / write:ai | AI chat tools |
admin:* | Platform admin only (not available via OAuth) |
agents:read, bots:write, etc.) still work.
MCP authentication
Send the same API key or OAuth token on every MCP request, includinginitialize. 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.