Authentication

The two-factor model that protects every gateway request: a bearer token plus your application secret.

Every protected request authenticates with two credentials. Both are required; a request missing either is rejected.

• Authorization: Bearer <access token>, a short-lived token issued by POST /v1/auth/token.
• x-zeam-auth: <application secret>, your application secret, issued when the application is registered. See API keys.

cURL

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

The only route that does not require this is the public token endpoint itself.

How verification works

The gateway verifies your bearer token on every request and resolves the association and roles it belongs to. Your request then runs against that association only.

• Association is never client-supplied. The gateway derives it from the verified token and attaches it downstream. Any association id you send in a URL or body is rejected, not honored.
• Isolation. An application can only read or change data within its own association.

Failure behavior

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

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 are separate environments with separate credentials. Credentials issued for the sandbox do not work in production. When you are promoted, you receive production credentials and switch the base URL. See Sandbox and Production promotion.

Next

API keys

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

Access tokens

Issue, use, and refresh the bearer token.