Skip to content
Ask the docs

Find answers across the QairoPay docs.

Type a question and we'll synthesize an answer from the docs with citations back to the source pages.

Tenancy model

QairoPay is multi-tenant at every layer of the stack. There is no global namespace for resources — a pass_01HZX issued by Tenant A is invisible to Tenant B at the API, the database, and the audit log.

Tenants and workspaces

A tenant is a legal entity (or division of one) operating a QairoPay program. When you sign up, you create one tenant. Larger customers run multiple tenants from a single workspace account, switching between them with the workspace switcher in the dashboard.

Workspace (your QairoPay account)
├── Tenant: Acme Hotels (live)
├── Tenant: Acme Hotels (sandbox)
└── Tenant: Acme Live Events (live)

Each tenant has:

  • Its own API keys, OAuth clients, and webhook endpoints.
  • Its own templates, passes, cards, and settlements.
  • Its own audit log.
  • Its own billing tier (separate invoices unless you’ve negotiated a master agreement).

API keys are tenant-scoped. A key from Tenant A cannot read or mutate Tenant B’s resources, even if both tenants live in the same workspace.

Resource IDs

All resource IDs are prefixed and globally unique:

PrefixResource
tnt_Tenant
tpl_Pass template
pass_Issued pass
card_Spend Card
txn_Card transaction
set_Settlement
evt_Webhook event
whk_Webhook endpoint
key_API key

The prefix lets you eyeball-validate which resource you’re looking at — useful when grepping logs. IDs are sortable lexicographically (we use a ULID variant under the hood), so ORDER BY id is the same as ORDER BY created_at within a tenant.

Cross-tenant operations

There is exactly one cross-tenant operation in the API: template export/import. A workspace admin can export a pass template from Tenant A and import it into Tenant B. This is a configuration-only operation; no pass data crosses the boundary.

Promotion from sandbox to live (see Sandbox vs live) is technically a cross-tenant operation under the hood, but the API surface treats it as a first-class verb (POST /v1/promotions).

Why this matters for your integration

  1. Don’t hard-code tenant IDs. The tenant is implicit in the API key; never include tenant_id in request bodies.
  2. One key per environment per tenant. If your product serves multiple QairoPay merchants (you’re a platform), use OAuth — see Authentication.
  3. Webhook endpoints are tenant-scoped. Each tenant registers its own endpoint. If you operate a multi-tenant integration, route events by the tenant_id field on the event envelope.