Authentication

The headers that protect every gateway request: a bearer token and your application secret.

Every request authenticates with x-zeam-auth; protected requests also carry a bearer token. A protected request missing either is rejected.

• x-zeam-auth: <application secret>, your application secret (API key), issued when the application is registered. Required on every request, including token issuance. See API keys.
• Authorization: Bearer <access token>, a short-lived token issued by POST /v1/auth/token. Required on every request except token issuance itself.

cURL

curl -sS https://api.zeam.money/gw/v1/wallets \
  -H "Authorization: Bearer $ZEAM_TOKEN" \
  -H "x-zeam-auth: $ZEAM_APP_SECRET"

The token endpoint is the one exception to Authorization — you don’t have a token yet. It still requires x-zeam-auth, like every other request.

How verification works

The gateway verifies your bearer token on every protected request and resolves your association from it server-side. You never send an association id yourself; associationId in the token response is informational only.

• Isolation. An application only reads or changes data within its own association.

Failure behavior

Authentication failures return a generic 401 problem response. The gateway does not reveal whether the token or the application secret was the cause. Treat any 401 as “re-authenticate and retry with valid credentials.”

A token that is otherwise valid but belongs to an application with no registered association returns 403 instead — re-authenticating won’t help; contact Zeam to complete registration.

Keep secrets server-side

Your client secret and application secret are confidential. Use them only from server-side code.

Never embed the client secret or x-zeam-auth in browser code, mobile apps, or any client a user can inspect. The gateway is a server-to-server API.

The gateway never logs bearer tokens, application secrets, or client secrets. You should hold the same standard on your side.

Sandbox and production credentials

Sandbox and production share the same base URL but use separate credentials; your application’s registration determines the environment. Credentials issued for the sandbox do not work in production. When you are promoted, you receive production credentials, and the base URL does not change. See Sandbox and Moving to production.

Next

API keys

How credentials are issued and which header each one maps to.

Access tokens

Issue, use, and refresh the bearer token.