API keys

Every key is a bearer secret: send it as Authorization: Bearer <key> on every /v1 call, from your server. Its prefix says what kind it is.

• wba_live_

  A LIVE key, for production.

• wba_test_

  A TEST key, for development, CI and staging. It is served exactly like a live key and its calls count against the same allowance; the separate prefix lets you keep it out of production code and revoke it on its own.

• wba_demo_

  The public demo key the reference's Try-it uses. It rotates daily, reads a fixed set of endpoints and has tight limits of its own. Never build on it.

Create, restrict and revoke keys in the developer console's Keys section. A key's secret is shown once, when it is made; store it in your secret manager straight away.

A key can be narrowed three ways. An empty list means no restriction of that kind. A call a restriction refuses answers 403 with code forbidden and metadata.errorCode PUBLIC_API_KEY_RESTRICTED.

• Scopes

  READ covers the catalogue reads, CHANGES the change feed (/v1/changes) and SOURCES the sources read (/v1/titles/{titleRef}/sources). /v1/account and its sub-paths need no scope, so a key can always read its own usage.

• IP allowlist

  Exact addresses or CIDR ranges, matched against the address your request reaches us from.

• Referrer allowlist

  Host names matched against the request's Referer host as a suffix; *.example.com covers its subdomains. A request with no Referer fails this check, so use it only for calls a browser makes and leave it empty for server keys.

Rotate a key from the console, or with the key itself: POST /v1/account/keys/{keyId}/rotate rotates only the key you call it with (any other id is 403 PUBLIC_API_KEY_SELF_ROTATE_ONLY).

POST /v1/account/keys/{keyId}/rotate
Authorization: Bearer wba_live_…   (the key being rotated)

• The new key

  The answer carries the new key's secret, once. Deploy it before the old one lapses.

• The old key

  Keeps working for 24 hours after the rotation, then stops.

• A second rotation

  While the old key is in its 24 hours, rotating it again answers 409 PUBLIC_API_KEY_ALREADY_ROTATED. If you lost the first answer, create a new key in the console and revoke the old one.

• Limits

  Rotation allows 40 calls an hour and 200 a day from one address.

• Every GET

  Read-only: repeating it changes nothing, so retry a timeout or a 5xx freely. A retried sources read that succeeds spends another verification; a refused or failed one spends none.

• POST …/rotate

  Not safe to repeat. A retry after a lost answer is refused with 409 and the new secret cannot be shown again (see above).

Retry a 429 only after the wait its Retry-After gives; the rate limits guide has a retry loop for each runtime.