> ## Documentation Index
> Fetch the complete documentation index at: https://paytectechnologies.mintlify.site/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.

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`](/authentication/tokens).
* `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](/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={null}
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
    GW->>Auth: Verify token
    Auth-->>GW: Valid, association + roles
    GW->>Svc: Call with association attached
    Svc-->>GW: Service response
    GW-->>App: Normalized REST response + X-Request-Id
```

## 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`](/api-reference/introduction).
2. **Payment**: you execute the intent as a payment, which the gateway submits
   for processing and accepts asynchronously. See
   [`POST /v1/payments`](/api-reference/introduction).

You then track progress by reading the intent state and by receiving
[webhook](/webhooks/overview) updates. The end-to-end path is walked in
[Make your first transaction](/guides/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](/access/sandbox).