Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Key concepts

Understand the key concepts behind The Wallet Crew: tenant, pass template, pass, environment and the API concepts (API key, passId, identifiers, metadata).

The Wallet Crew is built around a small set of concepts that appear throughout the platform. Understanding them once makes every other page faster to navigate.

Tenant

A tenant is the isolated unit for one brand or wallet program inside The Wallet Crew. Everything configured there lives inside that tenant: wallet designs, passes, data, credentials, API access, and team access.

A simple way to think about it is a private building, not a shared open space. What exists in one tenant does not mix with another tenant.

Most brands have one tenant. Some groups run several tenants when separate brands, countries, or programs must stay independent, with their own Apple and Google credentials, their own data, and their own teams.

A tenant is not a folder or a sub-account inside a shared account. Each tenant is fully isolated. There is no cross-tenant data access by design, and a key issued for one tenant cannot read or modify data of another.

Every path of the public API includes the tenant identifier (/api/{tenantId}/…).

Pass template

A pass template is the model for one type of wallet pass. It defines which wallet platform is targeted, how the pass looks, which fields appear, which barcode format is used, and how personalization works.

The easiest analogy is a blueprint. The template defines the rules once, then The Wallet Crew reuses those rules every time a new pass is created from it.

A template is not a pass. It does not belong to one customer. It is the reusable definition behind many passes.

One brand can use several templates at the same time. A loyalty card, a gift card, and an event ticket each usually need their own template.

Pass

A pass is one wallet card, ticket, or voucher issued to one customer. It is created from a template and linked to brand systems, such as a CRM, loyalty engine, POS, or ticketing platform.

If the template is the blueprint, the pass is the finished item in the customer’s wallet. One template can create thousands or millions of individual passes.

Passes move through a lifecycle:

  • Created — the pass exists on the platform.

  • Installed — the customer added it to Apple Wallet or Google Wallet.

  • Updated — the pass content changed, such as a points balance, status, or message.

  • Uninstalled — the customer removed it from the wallet.

Created and installed are two different moments. A pass can exist before a customer saves it to the wallet.

The Wallet Crew does not store customer personal data by default. Passes are usually linked through stable identifiers, such as a CRM ID or loyalty number, while core customer data stays in brand systems.

Environment

Environments separate testing from live operations. In practice, The Wallet Crew provides QA for testing and production for real customers.

QA is the rehearsal stage. Production is the live stage. QA mirrors production closely so testing reflects real conditions before launch.

These environments are fully isolated. A pass created in QA never appears in production, and production credentials or live data are not shared into QA.

Configuration can be copied between environments when needed.

Concepts for integrations

The concepts below matter when you connect The Wallet Crew to other systems through the API. They all attach to one thing: a pass, scoped to a tenant.

API key

An API key is a tenant-scoped credential for server-to-server calls. Send it in the X-API-KEY header. The permissions attached to the key control which operations are allowed.

See Getting started with the API for scopes and error codes.

Pass creation and pass management

Pass creation inserts a new pass into the platform. It happens through the Cinto SDK (the SDK for custom web and app enrolment flows), an enrolment form, a connector, or POST /passes.

Pass management is what the API does after that: forcing a refresh, recording a scan, sending a notification, or reading pass state.

If a flow must start from zero, see Enrolment flows.

Pass ID

passId is the internal identifier of a pass in The Wallet Crew. Platform operations that create or resolve a pass return it. Some endpoints use it for direct operations on one known pass, such as sending a notification. It is stable inside The Wallet Crew, which makes it useful for traceability.

External identifiers

External identifiers link a pass to source systems such as a CRM, loyalty engine, e-commerce platform, or ticketing system. Typical examples are a CRM customer ID, loyalty number, order ID, or ticket ID.

They let The Wallet Crew find the right pass without copying the full business record into the platform. One pass can hold several external identifiers when it depends on more than one source system. See Pass data and sync for the full data model.

Metadata and additional data

Both are stored on the pass, but they play different roles.

Field
Used for
How it is set

Metadata

Segmentation and targeting. Filter on it as metadata.<key>.

Computed from the pass template (Metadata rows, Liquid). It is refreshed on an update with options.updateMetadata. API calls do not set it.

Additional data

Enrichment when a value does not come from an external provider.

Sent by your system, for example in the additionalData object of an update.

Updates, targeting, and rendering depend on the right storage model: use metadata for values you target or filter on.

What comes next

FAQ

Can one template create many passes?

Yes. A template is the reusable definition behind many passes: one template can create thousands or millions of individual passes.

Why keep QA and production separate?

QA is the rehearsal stage and production is the live stage. The two environments are fully isolated: a pass created in QA never appears in production, and production credentials or live data are not shared into QA.

Can the same customer have several passes?

Yes. One customer may hold several passes from the same brand, such as one loyalty card and several event tickets. Each pass still remains its own record.

Is a tenant the same thing as an environment?

No. A tenant is an isolated brand or program. An environment is a platform stage such as production or QA.

Should integrations store passId or external identifiers?

Both can be useful. External identifiers are usually the natural bridge with source systems. passId is useful for direct operations once a pass is known inside The Wallet Crew.

Last updated