# tenants

Operators, customers, people (memberships), invitations, teams and customer settings (currencies, addresses, alerts, approved domains, approval policies, primary owner, closure).

## GET /customers

operationId: `listCustomers`
Summary: List customers (operator)
API key scopes: `customers:read`
Parameters: `X-Tenant-Id` (header, required), `X-Request-Id` (header), `cursor` (query), `limit` (query), `sort` (query), `filter` (query), `q` (query), `withTotal` (query)
Responses: 200 `CustomerPage`, 400 `Problem`, 401 `Problem`, 403 `Problem`, 429 `Problem`, default `Problem`

**API key scope:** `customers:read` (operator-level keys only, `X-Tenant-Id` = the operator id).

**Metadata filter:** `filter[metadata.<key>]=<value>` (exact match; at most 5; AND).

**Batch look-up (P12-T07):** `filter[id]=<id>,<id>,…` (at most 100) returns those rows only, e.g. to resolve names shown next to ids; combine with `limit` ≥ the number of ids.

## POST /customers

operationId: `createCustomer`
Summary: Create a customer (operator-initiated)
API key scopes: `customers:write`
Parameters: `X-Tenant-Id` (header, required), `X-Request-Id` (header), `Idempotency-Key` (header)
Request body: `CustomerCreate`
Responses: 201 `Customer`, 400 `Problem`, 401 `Problem`, 403 `Problem`, 409 `Problem`, 422 `Problem`, 429 `Problem`, default `Problem`

Creates a `draft` customer. With `primaryOwner` a primary-owner invitation is emailed; without it (console sessions only) no invitation is sent. Creates a draft customer and invites the primary owner. Self-registration uses `/auth/register`.

**API key scope:** `customers:write` (operator-level keys only, `X-Tenant-Id` = the operator id).

**API keys (review W3-02):** an operator key needs `customers:write`, the owner address must be on the operator settings' `apiKeyInvitationDomains` (`422 invitation_domains_required` / `domain_not_approved` before anything is written) and each key may create 10 customers a minute (`429`).

## GET /customers/{customerId}

operationId: `getCustomer`
Summary: Get customer
API key scopes: `customers:read`
Parameters: `customerId` (path, required), `X-Tenant-Id` (header, required), `X-Request-Id` (header), `If-None-Match` (header)
Responses: 200 `Customer`, 304, 401 `Problem`, 403 `Problem`, 404 `Problem`, 429 `Problem`, default `Problem`

`X-Tenant-Id` is the customer itself or its operator. `customer.view` is held by operator staff roles and by every customer role (own customer only).

**API key scope:** `customers:read` (operator-level keys only, `X-Tenant-Id` = the operator id).

## GET /customers/{customerId}/settings/currencies

operationId: `listCustomerCurrencies`
Summary: Account currencies (offered and enabled)
API key scopes: `balances:read`
Parameters: `customerId` (path, required), `X-Tenant-Id` (header, required), `X-Request-Id` (header), `If-None-Match` (header)
Responses: 200, 304, 401 `Problem`, 403 `Problem`, 404 `Problem`, 429 `Problem`, default `Problem`

**API key scope:** `balances:read`.