Skip to content
WallaB.AI

Docs / WallaB Developer Platform

Authentication & API keys

Bearer keys, the Growth-plan requirement, scopes, rotation, and keeping keys safe.

Every WallaB Developer Platform request is authenticated with an API key sent as a bearer token. This page is the single reference for keys, scopes, the plan requirement, and rotation.

Plan requirement

The Developer Platform is available on the Growth plan and above. On Free or Starter, key creation is locked and every request is refused with:

{ "success": false, "message": "Developer API access requires the Growth plan or higher." }

Because you own the key and the shop, this is a 403 (not a 401) — telling you to upgrade is not an information leak.

Creating a key

Create keys in Settings → WallaB Developer Platform. Key creation and revocation are owner-only — staff accounts can't mint credentials.

  • A key looks like wlb_ followed by 43 URL-safe characters.
  • It is shown exactly once, at creation. Only a salted hash is stored, so we can never show it again — copy it immediately.
  • A key can be revoked at any time; a revoked key fails on its very next request.

Using a key

Send the key as a bearer token on every request:

Authorization: Bearer wlb_your_key_here

Any missing, malformed, unknown, or revoked key gets the identical generic response — 401 {"success": false, "message": "Unauthorized"} — the API never reveals which check failed.

Heads up

Never expose a key client-side. It grants read access to your shop's data. Keep it on your server, in a secret manager or environment variable — never in browser JavaScript, a mobile app bundle, or a public repository.

Scopes

Each key carries one or more read-only scopes; grant only what a key needs:

  • read:entitlements — customer entitlement status.
  • read:subscriptions — subscription records and detail.
  • read:metrics — aggregate retention and revenue metrics (also governs cancel-save outcomes).
  • read:plans — selling-plan definitions.

A key that lacks the scope an endpoint requires is refused with 403 and a message naming the missing scope. Each endpoint's required scope is listed in the API reference.

Rotating a key

Keys don't expire on a timer — rotate on your own schedule, and immediately if a key may have leaked. Because you can hold several keys at once, rotation is zero-downtime:

  1. Create a new key with the same scopes.
  2. Deploy it to your integration.
  3. Revoke the old key once traffic has moved over.

Rate limits

Requests are limited per API key, by plan — Growth 60/min, Pro 300/min, Enterprise Plus uncapped. Over the limit returns 429 with a Retry-After header (seconds). See Rate limits for guidance.