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

# Authentication

> The headers that protect every gateway request: a bearer token, your application secret, and your association id.

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`](/authentication/tokens).
* `x-zeam-auth: <application secret>`, your application secret (API key), issued
  when the application is registered. See [API keys](/authentication/api-keys).
* `x-association-id: <association id>`, the association to scope the request to.
  Use the `associationId` returned when you issue a token.

```bash cURL theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
curl -sS https://api.zeam.money/gw/v1/wallets \
  -H "Authorization: Bearer $ZEAM_TOKEN" \
  -H "x-zeam-auth: $ZEAM_APP_SECRET" \
  -H "x-association-id: $ZEAM_ASSOCIATION_ID"
```

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](/platform/errors). 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`](/platform/errors).

## Keep secrets server-side

Your client secret and application secret are confidential. Use them only from
server-side code.

<Warning>
  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.
</Warning>

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](/access/sandbox) and [Moving to production](/access/production-promotion).

## Next

<CardGroup cols={2}>
  <Card title="API keys" icon="key-round" href="/authentication/api-keys">
    How credentials are issued and which header each one maps to.
  </Card>

  <Card title="Access tokens" icon="ticket" href="/authentication/tokens">
    Issue, use, and refresh the bearer token.
  </Card>
</CardGroup>