# API Key

API keys authenticate server-to-server calls to The Wallet Crew APIs. API keys are tenant-scoped. A key only works for a single tenant. Integrations spanning multiple tenants require one key per tenant.

API keys can also be scope-restricted. Least privilege reduces risk and limits blast radius.

<details>

<summary>Real-world examples</summary>

* A Brand CRM job updates loyalty points nightly, then triggers pass updates.
* An integration middleware issues new passes after an e-commerce checkout event.
* A data pipeline fetches pass installation status and sends it to analytics.

</details>

### Before you start

* An admin account with access to **Settings** is required.
* The intended usage and owning system are identified (service, job, connector).
* The minimum required scopes are listed. Each API endpoint documents its required scopes, and the admin console lists the available scopes at key creation time.

{% hint style="warning" %}
Never ship an API key in a mobile app or in front-end JavaScript. Treat it like a password.
{% endhint %}

### Create an API key

{% stepper %}
{% step %}

#### Open API Keys

1. Sign in to the admin console.
2. Go to **Settings → Security → API Keys**.

<p align="center"><a href="https://admin.thewalletcrew.io/tenant/~/settings/security/apiKeys" class="button secondary" data-icon="chevrons-right">The Wallet Crew - API Keys</a></p>
{% endstep %}

{% step %}

#### Add a new key

1. Click **Add new**.
2. Set a clear name.
   * Example: `crm-sync-prod` or `nightly-pass-update`.
3. Select the scopes you need.
4. Click **Save**.
   {% endstep %}

{% step %}

#### Copy and store the key

The key value is only displayed once, right after creation. After the dialog is closed, the value cannot be retrieved.

The key should be stored in a secret manager. Read access should be limited to the smallest set of services and operators needed to run the integration.
{% endstep %}
{% endstepper %}

### Use the key in API requests

Send the key in the `X-API-KEY` header.

Example header:

`X-API-KEY: <your_api_key>`

The full endpoint list and request/response formats are available in the [API reference](https://docs.thewalletcrew.io/develop/api-reference).

#### Validate access quickly

Authentication and authorization failures look similar, but mean different fixes. A quick validation flow helps isolate the issue early.

Run a low-impact `GET` request that matches the selected scopes. A `401 Unauthorized` response typically indicates a missing, invalid, or revoked key. A `403 Forbidden` response typically indicates a valid key with insufficient scopes.

### Manage, rotate, revoke

* **Rotate** keys regularly.
  * Create a new key.
  * Deploy it to your services.
  * Revoke the old key after a short overlap.
* **Revoke** keys immediately if they leak.
* Keep separate keys per environment and integration.

### Troubleshooting

* **401 Unauthorized**
  * Missing or invalid `X-API-KEY` header.
  * Key was revoked.
* **403 Forbidden**
  * Key is valid but missing required scope.

### FAQ

<details>

<summary>Can one API key be used across multiple tenants?</summary>

No. API keys are tenant-scoped. Each tenant requires its own key, even when the same integration runs in multiple tenants.

</details>

<details>

<summary>Can an API key be retrieved later if it was not copied?</summary>

API keys are meant to be shown once at creation time. If the value is lost, the safest path is to revoke the old key and create a new one.

</details>

<details>

<summary>What is the best way to name API keys?</summary>

A name should identify the owning system and environment. Names like `crm-sync-prod` or `data-export-staging` make rotation and incident response much faster.

</details>

<details>

<summary>How to rotate keys without downtime?</summary>

Create a new key and deploy it first. Keep both keys active during a short overlap. Revoke the old key once logs confirm the new key is used everywhere.

</details>

<details>

<summary>Where is the scope reference?</summary>

Each API endpoint documents the required scopes in its own documentation.

The admin console remains the place where available scopes can be reviewed and selected when creating or editing a key.

</details>