API keys

The API Keys tab issues bearer tokens for the Zubby AI public REST API. Use them to read your store’s conversations and leads from your own scripts and integrations, or to push catalog and order data from a custom storefront. Find it under Settings → API Keys, or go to /app/<storeId>/settings/api-keys. The card is titled Public API keys. Creating keys requires the Pro plan or above.

The secret is shown exactly once

When you create a key, the full token is displayed a single time, right after creation. Zubby stores only a hash of it - once you navigate away it cannot be recovered. Copy it immediately and store it in a secret manager. If you lose it, revoke the key and mint a new one.

Creating a key: step-by-step

Click Create key to open the form.
Enter a Name - a label so you can recognize the key later (e.g. analytics-export). Required, up to 120 characters.
Pick at least one scope:
- read - supported data-read endpoints, including conversations, leads, agent shopping and POST /loyalty/status. Checked by default; endpoint-specific plan and identity checks still apply.
- write - catalog/order ingestion and supported writes such as loyalty redemption. Leave it off unless the integration needs those operations; scope does not bypass endpoint entitlement or identity checks.
Submit with Create key. A green banner shows the new token with a Copy button; click Done once you’ve saved it.

If you pick no scopes, the form refuses with “Pick at least one scope.”

The key list

Existing keys appear below the create form. Each row shows:

Name and the key prefix (the first few characters, followed by an ellipsis) - enough to identify a key without exposing the secret.
A status badge: active or revoked.
The scopes the key carries, as badges.
When it was created, and either when it was last used or “never used.” Revoked keys also show their revocation time.

Revoking a key

Active keys have a Revoke button. Revoking is immediate and permanent - the dashboard warns that “existing requests using this key will start failing immediately.” You’ll be asked to confirm. Revoked keys stay in the list for audit history but can no longer authenticate.

Using a key

The public API authenticates with the bearer token alone - each key is bound to one store, so no store-ID header is needed. Treat keys like passwords: never commit them to source control, scope them to the minimum (read only where possible), and use a distinct key per integration so you can revoke one without breaking the others.

Key hygiene

Name keys after the system that uses them so an unfamiliar key on the list is an immediate red flag.
Rotate periodically: mint a replacement, cut the integration over, then revoke the old one.
Check the last used timestamps and revoke anything that hasn’t been used in a long time.

Storefront identity (custom stores)

Custom and headless stores also see a Storefront identity card here. It holds the signing secret your backend uses to sign a logged-in customer into the widget, which unlocks order lookups and loyalty points for that customer. Only store owners and admins can generate, rotate or revoke it, and like an API key it is shown once. Rotating it invalidates every token signed with the old secret at once. Managed Shopify Online Store and WooCommerce account flows have separate identity bridges. A headless loader alone does not establish a signed-in platform identity. See signing customers in for the token format and code samples.

For the endpoints these keys unlock, see the REST API reference. For event- driven integrations, see Webhooks. Widget embed credentials are separate - those live on the Workspace tab and are covered in Settings overview.

Verify a key without changing store data

Use a read-scoped key against a documented read endpoint, then confirm that a write request is rejected for insufficient scope. After rotating, repeat the read with the new key and confirm the revoked key returns an authentication error. Do these checks from a server-side test client and keep the key out of screenshots, browser JavaScript and logs.