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 the two credentials it accepts: API keys for machine-to-machine access, and interactive bearer tokens for the endpoints that require a logged-in session.

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.

Keys belong to a user, not to a community. There is no way to restrict a key to a single community, and none of the key management endpoints below take a communityId — a key reaches every community your account can reach. To scope a request to one community, pass the community ID to the endpoint you are calling, exactly as an interactive session would.

Prerequisites

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

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..."

Interactive bearer tokens

The three key management endpoints below authenticate with Authorization: Bearer <token> instead of an API key, as do the examples on every other page of this reference. A bearer token represents an interactive, logged-in session.

There is no login endpoint you can call to mint one programmatically — signing in is protected by CAPTCHA, which is precisely why API keys exist for machine-to-machine access. To obtain a token for manual use, log in to the Babele frontend application, then open your browser console (F12, or right click -> Inspect and then select the Console tab) and run the following command:

'Bearer ' + JSON.parse(localStorage.getItem('app-storage')).state.token

This should give you a result that looks like this:

'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJleGFtcGxlIiwiZXhwIjoxNzQzODY1MjA3fQ.DEMO_SIGNATURE_NOT_A_REAL_TOKEN'

Send that value as the Authorization header, exactly as the examples throughout this reference do. A login token is valid for 7 days; once it expires, requests return 401 Unauthorized and you need to log in again and re-read the value. A token issued while impersonating another user lasts only 1 hour.

Creating a key

curl -X POST https://api.babele.co/api/apikey \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJleGFtcGxlIiwiZXhwIjoxNzQzODY1MjA3fQ.DEMO_SIGNATURE_NOT_A_REAL_TOKEN" \
  -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 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJleGFtcGxlIiwiZXhwIjoxNzQzODY1MjA3fQ.DEMO_SIGNATURE_NOT_A_REAL_TOKEN"

[
  {
    "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
  },
  {
    "id": 37,
    "keyId": "bbl_live_8c2d40e1f6ab97b3",
    "name": "Reporting export",
    "createdAt": "2026-01-10T08:00:00Z",
    "expiresAt": "2026-04-10T08:00:00Z",
    "lastUsedAt": null,
    "isExpired": true
  }
]

Revoking a key

curl -X DELETE https://api.babele.co/api/apikey/42 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJleGFtcGxlIiwiZXhwIjoxNzQzODY1MjA3fQ.DEMO_SIGNATURE_NOT_A_REAL_TOKEN"

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.