API Keys & Secrets

Manage the three types of credentials used to authenticate API calls, SDK integrations, and connector connections.

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.

Real-world examples

• 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.

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.

Never ship an API key in a mobile app or in front-end JavaScript. Treat it like a password.

Create an API key

1

Open API Keys

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

The Wallet Crew - API Keys

2

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.

3

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.

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.

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

Can one API key be used across multiple tenants?

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

Can an API key be retrieved later if it was not copied?

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.

What is the best way to name API keys?

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.

How to rotate keys without downtime?

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.

Where is the scope reference?

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.

General secrets

General secrets are named credentials used by SDK integrations. Create a General secret when an SDK integration requires a shared secret that is not an API key.

Create a General secret

1. Go to Settings → Access Control → API Keys & Secrets.
2. Open the General secrets tab.
3. Click Add new and give the secret a clear name.
4. Copy the value immediately. It is only shown once.

Store the value in the integration's secret manager. Treat it with the same care as an API key.

App secrets

App secrets are credentials that connectors use to authenticate against external systems. Examples include passwords and access tokens for a CRM, POS, or marketing platform.

Most connectors manage App secrets through their own setup UI. Direct edits in this tab are rarely needed. The connector configuration flow handles them.

View or update an App secret manually

1. Go to Settings → Access Control → API Keys & Secrets.
2. Open the App secrets tab.
3. Select the secret to edit.

When setting up a connector, use its configuration UI rather than editing App secrets directly. The connector UI guides the setup and validates the credentials.