> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zeam.money/llms.txt
> Use this file to discover all available pages before exploring further.

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

Your association is fixed to your application. You receive its id as
`associationId` when you [issue a token](/authentication/tokens), and you send
that id as the `x-association-id` header on every protected request. The gateway
scopes all data to it, so one application only ever acts within its own
association.

## Request authentication

Every protected request carries three headers:

* `Authorization: Bearer <access token>`, a short-lived token from
  [`POST /v1/auth/token`](/authentication/tokens).
* `x-zeam-auth: <application secret>`, your application secret (API key), issued
  at registration.
* `x-association-id: <association id>`, the association to scope the request to.

The gateway verifies the token server-side on every request and scopes the
request to your association. A protected request without `x-association-id`
returns `412`. See [Authentication](/authentication/overview).

## 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`](/api-reference/introduction). You never write GraphQL.

The result is a uniform contract:

* Resource-oriented routes under `/v1`, camelCase fields.
* [Cursor pagination](/platform/pagination) on collections.
* [RFC 7807 problem responses](/platform/errors) on every error.
* An `X-Request-Id` on every response for support correlation.

## Request lifecycle

```mermaid theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
sequenceDiagram
    participant App as Your application
    participant GW as Zeam API Gateway
    participant Auth as Auth
    participant Svc as Downstream service

    App->>GW: Request + Bearer token + x-zeam-auth + x-association-id
    GW->>Auth: Verify token
    Auth-->>GW: Valid, roles
    GW->>Svc: Call scoped to association
    Svc-->>GW: Service response
    GW-->>App: Normalized REST response + X-Request-Id
```

## Wallets and balances

Each **wallet** in your association has a Stellar public key. Balances
(on-chain trustlines) are embedded directly in the wallet resource and returned
by [`GET /v1/wallets`](/api-reference/introduction),
[`GET /v1/wallets/{walletId}`](/api-reference/introduction), and
[`POST /v1/wallets`](/api-reference/introduction). Balance enrichment is
best-effort: a transient Horizon failure leaves `balances` empty rather than
failing the whole request.

Before creating a wallet, use [`GET /v1/wallet-types`](/api-reference/introduction)
and [`GET /v1/networks`](/api-reference/introduction) to discover valid
`typeId` and `networkId` values.

## The payment model

You move money by submitting a payment directly:

* [`POST /v1/payments/p2p`](/api-reference/introduction): a same-asset transfer.
* [`POST /v1/payments/swap`](/api-reference/introduction): a cross-asset transfer.
* [`POST /v1/payments/offramp`](/api-reference/introduction): a cash-out to a
  real-world destination, executed against a [quote](/api-reference/introduction).

Payments are **asynchronous**: submission returns `202 Accepted` with a
`transactionRecordId`. Track the outcome by polling the
[transactions](/api-reference/introduction) routes or by receiving
[webhook](/webhooks/overview) updates. The end-to-end path is walked in
[Your first transaction](/guides/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](/access/sandbox).