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

# Core concepts

> How brands, venues, and integrators fit together in the Clopos Open API v2

# Core concepts

Before building against the API, it helps to understand the four identifiers that appear on every v2 request: **brand**, **venue**, **integrator**, and the JWT that ties them together.

## Brand

A **brand** is the top-level tenant on the Clopos platform. Every restaurant chain, cloud kitchen, or coffee shop operator has its own brand, identified by a short string such as `openapitest`. All data — venues, products, orders, receipts — lives inside a brand.

You receive your `brand` identifier from Clopos when your account is provisioned.

## Venue

A **venue** is a physical location that belongs to a brand — a single restaurant, branch, or kiosk. A brand can have one venue or hundreds. Venues are identified by numeric IDs (for example, `venue_id: 1`).

Each JWT is issued with a default `venue_id` encoded inside it. You can override it on any request with the optional `x-venue` header, which is useful when a single integration needs to operate across multiple venues under the same brand without re-authenticating.

```bash theme={null}
# Default venue (from the JWT)
curl "https://integrations.clopos.com/open-api/v2/products" \
  -H "x-token: eyJhbGciOi..."

# Override the venue for this request only
curl "https://integrations.clopos.com/open-api/v2/products" \
  -H "x-token: eyJhbGciOi..." \
  -H "x-venue: 7"
```

## Integrator

An **integrator** represents the third-party system talking to the Clopos API — a delivery marketplace, a loyalty platform, an ERP connector, and so on. Each integrator is registered with Clopos and receives a unique `integrator_id`.

Integrators are a v2 concept and are **required** on every authentication call. They allow Clopos to:

* Attribute traffic and rate limits to a specific partner.
* Gate access to experimental or test-only brands.
* Revoke a single partner's access without rotating every client credential.

### Test vs production integrators

Integrators are flagged as either `is_test: true` or `is_test: false`. The rule enforced on both `/v2/auth` and every authenticated endpoint is:

<Warning>
  A **test integrator** (`is_test: true`) can only call **non-production brands**. If a test integrator attempts to call a production brand, the API rejects the request with the error `"Integrator is in test mode. But brand is not in test mode"`.
</Warning>

Use a test integrator while you are building and verifying your integration against a sandbox brand. When you are ready to go live against a real brand, request a production `integrator_id`.

## JWT access token

Once you call `/v2/auth` with `client_id`, `client_secret`, `brand`, and `integrator_id`, Clopos returns a signed JWT that encodes all of the above plus the default `venue_id` and upstream authentication state.

That is why authenticated v2 requests need only a single header (`x-token`) — everything else is already inside the token.

```
┌──────────────────── JWT payload ────────────────────┐
│  brand           your brand identifier              │
│  venue_id        default venue (override with       │
│                  x-venue header)                    │
│  integrator_id   your integrator identity           │
│  stage           brand environment (test / prod)    │
│  expires_at      Unix timestamp, ~1h from issue     │
└──────────────────────────────────────────────────────┘
```

Tokens are short-lived. Refresh them a little before `expires_at` rather than waiting for a `401 Token expired`. See [Authentication](/authentication) for the full flow and code examples.

## Putting it together

A typical v2 request therefore carries:

1. A JWT in `x-token` that authenticates **who** is calling (integrator) and **where** they are calling (brand + default venue).
2. Optionally `x-venue` to target a different venue under the same brand.
3. The request body or query parameters for the endpoint itself.

```bash theme={null}
curl -X GET "https://integrations.clopos.com/open-api/v2/receipts?limit=20" \
  -H "x-token: eyJhbGciOi..." \
  -H "x-venue: 3"
```

All interaction on v2 is currently synchronous and client-initiated. [Webhooks](/webhooks) are on the roadmap; until they ship, poll the relevant list endpoints with a sensible interval, keeping the [rate limits](/rate-limits) in mind.