Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.ceibo.me/llms.txt

Use this file to discover all available pages before exploring further.

Ceibo exposes two distinct authentication models:
SurfaceAudienceAuthHeader
api.ceibo.me/v1Third-party developers consuming the APIAPI keyx-api-key: <key>
Developer dashboard endpointsLogged-in account holders managing their own keysSupabase JWTAuthorization: Bearer <jwt>
The two paths run on separate gateways with different routing — an API key is never valid against dashboard endpoints, and a JWT is never valid against the public API.

​
API keys

API keys authenticate every public-data request — countries, cities, walking tours, entry requirements, and the rest.

​
Header format

Send the key as the x-api-key header: 
GET /v1/countries?limit=10 HTTP/1.1
Host: api.ceibo.me
x-api-key: ck_live_…
Accept: application/json
Sending multiple x-api-key headers on the same request is rejected with 400 Bad Request. This guards against header-smuggling attempts by upstream proxies.

​
Constraints

  • Up to 5 active keys per account. Revoke unused keys to free a slot.
  • The plaintext key is shown once at creation and never persisted in recoverable form. Store it in a secrets manager.
  • Names are unique per account — duplicates return 409 Conflict.
  • Revocation is soft (sets revoked_at) and idempotent. Revoked keys remain visible in the dashboard for audit but are rejected by the API.

​
Rotation

There is no in-place rotation. To rotate:
  1. Mint a new key in the dashboard.
  2. Deploy it to your client.
  3. Revoke the old key.
Rolling overlap windows are how you avoid downtime.

​
JWT (developer dashboard)

The dashboard endpoints — managing your own keys, viewing usage, checking your subscription — use a Supabase-issued JWT in the standard Authorization: Bearer header. You will not normally call these endpoints directly; the developer dashboard handles them. They exist for tooling and CI scripts that need programmatic access to a specific user’s account. 
GET /v1/api-keys HTTP/1.1
Host: app-api.ceibo.me
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6Ikp...
Dashboard endpoints additionally require a real user — anonymous Supabase sessions cannot mint or manage keys. Sign up before attempting key management calls.

​
Subscription tiers

Every key carries a tier derived from the account’s developer subscription. Tiers gate request volume and rate limits.
TierStatus
FreeDefault for every signup. No subscription row.
GrowthPaid via Stripe checkout from the dashboard.
BusinessPaid via Stripe checkout from the dashboard.
MVP note. Tier-based rate limiting is staged but not yet enforced at the gateway. Keys are minted with the correct tier and the enforcement layer will roll out without API contract changes — your existing integrations will not need to change when limits go live. Watch the developer dashboard for the current per-tier quota.

​
Errors

Auth failures return a structured error envelope (see API reference / Errors):
StatusCodeCause
401UNAUTHORIZEDMissing, malformed, revoked, or unknown key/JWT
403FORBIDDENAuthenticated but not allowed (e.g. anonymous user attempting key management)
429RATE_LIMIT_EXCEEDEDTier quota or burst limit exceeded