Skip to main content
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:
On its own, either header returns 401. The complete signed requests are in the 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 signs JSON.stringify of 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.
REST HMAC uses milliseconds and includes the HTTP method and path. This is different from inbound agent webhook signing, which uses seconds and canonical JSON only.

Signed request helper

Every REST example in these docs uses this small shell function. Paste it into your shell once, after exporting EZ_API_KEY and EZ_SECRET:
Write numbers in request bodies the plain way (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.
Pass the path exactly as you want it requested, including any query string, because the query string is part of the signed text. The helper compacts your JSON with 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)

The SDK signs every API-key request by default when hmacSecretKey is configured. Or sign manually with signRestRequest:

HMAC error responses

MCP authentication

API keys (with required HMAC) work on POST 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.