Skip to main content
Every protected request authenticates with three headers. A request missing any of them is rejected.
  • Authorization: Bearer <access token>, a short-lived token issued by POST /v1/auth/token.
  • x-zeam-auth: <application secret>, your application secret (API key), issued when the application is registered. See API keys.
  • x-association-id: <association id>, the association to scope the request to. Use the associationId returned when you issue a token.
cURL
The only route that does not require these is the public token endpoint itself.

​
How verification works

The gateway verifies your bearer token on every request and resolves the roles it carries. Your request runs against the association you pass in x-association-id, which is fixed to your application and returned as associationId when you issue a token.
  • Association scope. Send your association id as x-association-id on every protected request. A protected request without it returns 412.
  • Isolation. An application only reads or changes data within its own association.

​
Failure behavior

Authentication failures return a single, 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 missing x-association-id header is a separate 412.

​
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.