API concepts

How the gateway authenticates you, scopes your data, and normalizes the platform behind one REST contract.

A few ideas explain almost everything about how the gateway behaves. Read this once and the rest of the docs will make sense.

Applications and associations

An association is a Zeam business tenant. An application is a registered integration bound to exactly one association. Your application credentials identify you; the association defines the data you can see.

You never pass an association id in a request. The gateway derives it from your verified token and applies it for you. This is why one application can only ever act within its own association.

Two-factor request authentication

Every protected request carries two things:

• Authorization: Bearer <access token>, a short-lived token from POST /v1/auth/token.
• x-zeam-auth: <application secret>, your application secret, issued at registration.

The gateway verifies the token server-side on every request and resolves your association and roles from it. See Authentication.

One contract over many services

The platform behind the gateway uses different transports and auth models. The gateway hides that. The clearest example is connector discovery: internally it is a GraphQL query, but the gateway surfaces it as a plain REST collection at GET /v1/connectors. You never write GraphQL.

The result is a uniform contract:

• Resource-oriented routes under /v1, camelCase fields.
• Cursor pagination on collections.
• RFC 7807 problem responses on every error.
• An X-Request-Id on every response for support correlation.

Request lifecycle

The transaction model

Moving money is a two-step model:

1. Intent: you initiate a transaction intent describing what should happen (for example a P2P transfer). See POST /v1/intents.
2. Payment: you execute the intent as a payment, which the gateway submits for processing and accepts asynchronously. See POST /v1/payments.

You then track progress by reading the intent state and by receiving webhook updates. The end-to-end path is walked in Make your first transaction.

Environments

There are two environments: a sandbox for building and testing, and production for live traffic. You start in the sandbox and are promoted to production after validation and operational readiness. See Sandbox.