Authentication and Authorization

You'll need to authenticate your requests to access any of the endpoints in the Babele API. In this guide, we'll look at how authentication works using API keys.

API key authentication

API keys let you call the Babele API programmatically (machine-to-machine) without going through the interactive login flow. You authenticate a request by sending your key in the X-API-Key header.

A key works on the same endpoints your user account can access, except sensitive self-management endpoints (changing your password or email, disabling your account, impersonation, and managing API keys themselves), which still require an interactive login.

Prerequisites

• You must be an administrator of at least one community to create a key.
• Platform administrators cannot create keys.

Getting and managing your keys

The easiest way to create and manage your keys is from the Babele frontend application. Once logged in, open the developer settings screen at /account/settings?section=developer.

From there you can create new keys, see when each was last used, and revoke keys you no longer need. The plaintext key is shown only once, right after you create it — store it securely immediately, because it can never be retrieved again. If you lose it, revoke it and create a new one.

The frontend screen calls the management endpoints documented below. These endpoints require an interactive (logged-in) session, so they cannot be called with an API key.

Using a key

Send the full key in the X-API-Key header on every request. Do not put it in the Authorization: Bearer header — that header is reserved for interactive sessions.

curl https://api.babele.co/api/user/getcurrent \
  -H "X-API-Key: bbl_live_3f9a1c7b2d4e5f60.Xy7...redacted..."

Creating a key

curl -X POST https://api.babele.co/api/apikey \
  -H "Content-Type: application/json" \
  -d '{"name":"CI pipeline","expiresInDays":90}'

{
  "id": 42,
  "key": "bbl_live_3f9a1c7b2d4e5f60.Xy7...redacted...",
  "keyId": "bbl_live_3f9a1c7b2d4e5f60",
  "name": "CI pipeline",
  "createdAt": "2026-06-28T12:00:00Z",
  "expiresAt": "2026-09-26T12:00:00Z"
}

Listing your keys

curl https://api.babele.co/api/apikey

[
  {
    "id": 42,
    "keyId": "bbl_live_3f9a1c7b2d4e5f60",
    "name": "CI pipeline",
    "createdAt": "2026-06-28T12:00:00Z",
    "expiresAt": "2026-09-26T12:00:00Z",
    "lastUsedAt": "2026-06-28T12:05:00Z",
    "isExpired": false
  }
]

Revoking a key

curl -X DELETE https://api.babele.co/api/apikey/42

Expiry and rotation

Keys expire automatically, with a maximum lifetime of 180 days. Rotate before expiry to avoid downtime: create the new key, switch your integration over to it, then revoke the old one.

Rate limits

Each key is limited to 1000 requests per hour by default. Exceeding the limit returns 429 Too Many Requests with a Retry-After header (in seconds). Repeated violations extend the lockout window progressively.

Security notes

• Keys are stored only as a one-way hash; Babele can never show you a key again after creation.
• The bbl_ prefix lets secret scanners recognise leaked keys — revoke any key you suspect is exposed.

Authorization

The Babele API uses role-based access control (RBAC) to manage permissions. Each user has a set of roles that determine what actions they can perform and what resources they can access. The roles are defined in the Babele platform and are assigned to users based on their membership in communities or projects. Because an API key acts as the user who created it, it carries that same set of roles. For many of the endpoints in this documentation, you will need to be an admin user to have the permissions to access them.