Key concepts
Understand the core API concepts used across The Wallet Crew developer guides.
Key concepts
This page defines the platform concepts that appear across The Wallet Crew API guides. It is the quickest way to align on tenant scope, pass identifiers, and the difference between pass creation and pass management.
Real-world examples
One brand can run one tenant for Europe and one tenant for North America.
One pass can contain both a CRM customer ID and a ticket ID as external identifiers.
One integration can create passes with the Cinto SDK, then update them later through the API.
Tenant
A tenant is the main isolation boundary in The Wallet Crew. Data, configuration, credentials, and API access are all scoped to a tenant.
In practice, a tenant usually represents one brand, one region, or one program that must stay isolated from others. A key issued for one tenant cannot read or modify data from another tenant.
Every API path includes the tenant identifier as a path parameter.
Use Infrastructure for the full tenant and environment model.
API key
An API key is a tenant-scoped credential used to authenticate server-to-server calls.
The key is sent in the X-API-KEY header. Permissions attached to the key control which operations are allowed. Missing permissions usually return 401 or 403 depending on the endpoint and authorization flow.
Pass creation vs pass management
The Wallet Crew separates pass creation from pass management.
Pass creation happens through the Cinto SDK or through connectors. This is the step that inserts a new pass into the platform.
The API is mainly used after that step. Common operations are forcing a refresh, recording a scan, sending a notification, or reading pass state.
If a flow must start from zero, use the relevant Enrolment flows or Connector-triggered pass creation guide.
Pass template
A pass template defines how a pass is rendered in Apple Wallet and Google Wallet. It controls layout, field mapping, images, barcode settings, and which dynamic values are displayed.
Templates are configured in the back-office before passes are issued or updated. A template does not represent one pass. It represents the reusable definition shared by many passes.
When a pass is refreshed, The Wallet Crew rebuilds the wallet artifact from the pass data, the template, and provider data.
Use How a pass is rendered for the render pipeline.
Pass ID
passId is the internal identifier of a pass in The Wallet Crew.
It is returned by platform operations that create or resolve a pass. Some endpoints use passId for direct operations on one known pass, such as sending a notification to that pass.
passId is stable inside The Wallet Crew. It is useful for traceability and for direct pass operations.
External identifiers
External identifiers link a pass to source systems such as a CRM, loyalty engine, e-commerce platform, or ticketing system.
These identifiers are often the most important API concept because they let The Wallet Crew find the right pass without copying the full business record into the platform. Typical examples are a CRM customer ID, loyalty number, order ID, or ticket ID.
One pass can contain several external identifiers. This is common when the same pass depends on more than one source system.
Use Structure for the full pass data model.
Metadata and additional data
Metadata and additional data are both stored on the pass, but they serve different roles.
Metadata is used for segmentation and targeting. Additional data is used for pass enrichment when a value does not come from an external provider.
This distinction matters because updates, targeting, and rendering depend on the right storage model.
FAQ
Is a tenant the same thing as an environment?
No. A tenant is an isolated customer workspace. An environment is a platform stage such as production or QA. The same customer can have one tenant in more than one environment.
Last updated