> For the complete documentation index, see [llms.txt](https://docs.thewalletcrew.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.thewalletcrew.io/developers-guides/readme/key-concepts.md).
# Key concepts
## 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](/developers-guides/pass-architecture/infrastructure.md) 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](/developers-guides/integration-guides/wallet/enrolment-flows.md) or [Connector-triggered pass creation](/developers-guides/integration-guides/wallet/connector-triggered-pass-creation.md) 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](/developers-guides/pass-architecture/how-a-pass-is-rendered.md) 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](/developers-guides/pass-architecture/structure.md) 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.
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.
Can one pass use more than one external identifier?
Yes. This is a common setup when data comes from several systems.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.thewalletcrew.io/developers-guides/readme/key-concepts.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.