Authentication

All API endpoints use Bearer token authentication with scoped API keys.

How it works

API keys begin with the prefix lb_api_ and are passed in every request using the Authorization header:

Authorization: Bearer lb_api_YOUR_KEY

Keys are hashed at rest using bcrypt — the raw value is shown only once at the moment of creation. If you lose a key, revoke it and create a new one.

Create an API key

You must be logged in via a session cookie to create keys. Send a POST to /api/v1/me/keys with the key name and the scopes you need:

curl -X POST https://listenbrief.com/api/v1/me/keys \
  -H "Cookie: session=YOUR_SESSION" \
  -H "Content-Type: application/json" \
  -d '{"name":"My App","scopes":["read","write","webhooks:write","usage:read"]}'

const res = await fetch('https://listenbrief.com/api/v1/me/keys', {
  method: 'POST',
  credentials: 'include', // sends session cookie
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    name: 'My App',
    scopes: ['read', 'write', 'webhooks:write', 'usage:read'],
  }),
});
const { key } = await res.json();
// key.secret is shown only once — store it now
console.log(key.secret);

API keys are shown exactly once on creation. Store them securely in a password manager or secrets manager.

Scopes

Scopes limit what an API key can do. Grant only the scopes your application actually needs.

Scope	Description
`read`	GET all resources (profiles, sources, briefings, schedules, webhooks)
`write`	POST / PATCH / DELETE all resources
`webhooks:write`	Create and delete webhooks
`usage:read`	Access the `/api/v1/usage` endpoint

Key rotation

To rotate a key: revoke the old one, create a new one, then update your configuration. Zero-downtime rotation is possible by creating the new key first, deploying the new value, then revoking the old one.

Revoke a key by sending a DELETE request with the key ID:

curl -X DELETE https://listenbrief.com/api/v1/me/keys/{keyId} \
  -H "Cookie: session=YOUR_SESSION"

After revoking, all requests made with the old key will immediately return 401 Unauthorized.

Security best practices

Never commit API keys to git — use .gitignore on .env files.
Store keys in environment variables (LISTENBRIEF_API_KEY), not in source code.
Use short-lived, narrowly-scoped keys for CI/CD pipelines.
Rotate every 90 days as a baseline hygiene practice.
Grant only the minimum scopes required for each integration.
Audit active keys regularly from Settings → API Keys and revoke any you no longer use.