API Keys & Authentication

Authenticate API requests with API keys or Firebase ID tokens, and manage key roles.

Overview

Management endpoints (projects, buffers, analytics, DLQ, API keys, credits and billing) require one of:

Method	Header	Typical use
API key	`X-API-Key: wbk_…`	Servers, scripts, CI/CD
Firebase ID token	`Authorization: Bearer <ID token>`	The dashboard, which signs you in with Firebase Authentication

If a request has both, the API key is used. Use API keys for anything you automate: ID tokens expire after an hour and are tied to a person.

The ingest endpoint (POST /v1/ingest/{projectId}/{bufferId}) does not require authentication. If you send X-API-Key to it, the key must be valid, belong to the buffer's account and, if it is project-scoped, include the buffer's project.

Creating an API key

Via dashboard

Sign in at webbu.dev
Go to Settings → API Keys
Create a key with a descriptive name (e.g. "Production server"), a role and, optionally, the projects it may access
Copy the key right away: it is shown only once

Via API

curl -X POST https://webbu.dev/api/v1/admin/api-keys \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $WEBBU_API_KEY" \
  -d '{"name": "CI pipeline", "role": "member", "projectIds": ["p_shop"]}'

{
  "keyId": "ak_4f1c9b2e7a3d5c80",
  "name": "CI pipeline",
  "secret": "wbk_9f8e7d6c5b4a39281706f5e4d3c2b1a09f8e7d6c5b4a3928",
  "keyPrefix": "wbk_9f8e",
  "role": "member",
  "projectIds": ["p_shop"],
  "createdAt": "2026-01-15T10:00:00.000Z"
}

role defaults to your own role and can't be higher than it. projectIds is optional (all projects when omitted) and can't be broader than your own access. Webbu stores only a hash of the key, so the secret can't be retrieved later.

Using an API key

curl -H "X-API-Key: wbk_your_key_here" \
  https://webbu.dev/api/v1/admin/projects

Keys are wbk_ followed by 48 hexadecimal characters. The fixed prefix helps secret scanners (GitHub, GitGuardian) spot leaked keys.

Roles and permissions

API keys and dashboard users have one of four roles:

Action	viewer	member	admin	owner
Read projects, buffers, analytics, DLQ, credits, invoices, API keys	✓	✓	✓	✓
Create, update, delete, clone and test buffers		✓	✓	✓
Create, update and delete projects			✓	✓
Create and revoke API keys			✓	✓
Retry and delete DLQ entries			✓	✓
Cancel the subscription immediately			✓	✓
Cancel the subscription at the end of the period				✓

Ingest accepts a key of any role. A request without the required role gets 403 with "message": "Requires one of the following roles: …". The person who signs up is the account owner.

Recommendation: give services that only read data a viewer key, scope keys to the projects they need, and keep admin/owner keys for management scripts.

Managing keys

List keys

curl -H "X-API-Key: $WEBBU_API_KEY" \
  https://webbu.dev/api/v1/admin/api-keys

The list shows each key's name, prefix, role, projects, creation date and last use, never the secret.

Revoke a key

curl -X DELETE -H "X-API-Key: $WEBBU_API_KEY" \
  https://webbu.dev/api/v1/admin/api-keys/ak_4f1c9b2e7a3d5c80

Revoked keys stop working immediately (401 Invalid or revoked API key). Revoking an already revoked key returns 409.

Key rotation

Create a new key with the same role and projects
Deploy it to your application and verify it works
Revoke the old key

Limits

Each account can have up to 10 active API keys. Creating more returns 409 Conflict; revoke unused keys to free a slot.

Firebase ID tokens

The dashboard calls the same API with the signed-in user's Firebase ID token. Password accounts must have a verified email address; otherwise the API answers 403 with "code": "email_not_verified".

API Keys & Authentication

On this page