Every call authenticated with an API key needs
x-api-key, x-timestamp and x-signature. Sending only x-api-key returns 401. The ezs_ secret is not optional.API key authentication
Send your developer API key on every authenticated request in either header, together with the signing headers described below:ez helper and the curl examples further down. Do not copy a bare key-only request.
Create and revoke keys in the Dev Portal. Each key has scoped permissions - request only the scopes your integration needs.
Scopes
Each key carries scopes. The full list is in Authentication overview; request only what your integration needs.Required REST HMAC signing
Every API-key authenticated request must be signed with the API secret returned when the key was created. JWT and OAuth bearer session tokens are exempt.String to sign
METHOD- uppercase HTTP verb (GET,POST, …)path- full request path including query string (e.g./api/v1/developers/earnings)body- the compact JSON for POST/PUT/PATCH (no spaces or line breaks between tokens), or an empty string when there is no body. The server signsJSON.stringifyof the parsed body, so send compact JSON and sign exactly the string you send. A body with extra spaces or line breaks produces a 401.
Signed request helper
Every REST example in these docs uses this small shell function. Paste it into your shell once, after exportingEZ_API_KEY and EZ_SECRET:
1, 0.5, 1000), not 1.0, 0.50 or 1E+3. The server signs the body as JavaScript re-serialises it, and jq keeps numbers as you typed them, so 0.50 would sign differently and return 401.
jq -c and signs and sends that same compact string, because the server signs JSON.stringify of the parsed body. The x-ez-mcp-client header carries a short label for your client (set EZ_CLIENT to change it). The API spec lists it as required on POST /api/v1/agents; whether it is enforced is not confirmed, so send it on agent create calls.
The timestamp comes from
python3 on purpose. date +%s%3N only works on GNU/Linux. On macOS it prints a literal N, and the call fails with Invalid x-timestamp value. A perl one-liner such as perl -MTime::HiRes=time -e 'printf "%d", time*1000' works too.curl example (GET)
The helper above does the following, written out step by step:curl example (POST)
This example posts to the sandbox signal simulator, which has no side effects. Use an agent id you own.Python (echozero-sdk)
hmac=True is the default for API-key clients, so every request is signed automatically.
TypeScript (echozero-sdk)
hmacSecretKey is configured.
Or sign manually with signRestRequest:
HMAC error responses
MCP authentication
API keys (with required HMAC) work onPOST https://mcp.echozero.app/mcp the same way as REST. Send x-api-key or Authorization: Bearer on every MCP call, including initialize. See the MCP Server guide.