API keys and scopes
How keys work and what each scope can do.
Keys look like bx_live_ followed by 32 characters. Send them as Authorization: Bearer <key>. A key can have an expiry date, set when you create it. A revoked or expired key answers 401 UNAUTHORIZED.
There are two scopes:
- upload: uploads files, reads everything, sends logs. Cannot delete. Works on every plan, free included. Use this scope in anything you distribute or put in a resource folder.
- full: everything. Needs a paid plan. On the free tier a full key answers
403 PLAN_REQUIRED.
| Action | upload | full |
|---|---|---|
| Upload (direct, presigned, base64, compatible endpoints, zip import) | yes | yes |
Read files, stats, trash, import status, /me | yes | yes |
| Create a folder | yes | yes |
| Send and search logs | yes | yes |
| Read log categories, read and update player profiles | yes | yes |
| Grant or revoke site access (player-only sites) | yes | yes |
| Delete a file, restore or purge from the trash | no | yes |
| Set folder retention, delete a folder | no | yes |
| Create, edit or delete log categories | no | yes |
| Saved views and alert rules (read and write) | no | yes |
| Delete a player profile | no | yes |
| Deploy a site | no | yes |
The number of active keys depends on your plan (see Plans and limits). On the free tier, keys are upload scope only.
Each key belongs to the team member who created it. Endpoints that check the person's role (database access) or need an owner (personal saved views) use that member. Keys created before keys were tied to their creator get 403 FORBIDDEN there: create a new key.
GET /api/v1/me returns key.scope, so a script can check what it may do before it tries.
Never put a key in browser code or in a client script. Every player could read it. Keep it on your server. To let a client upload, give it a presigned URL (see below).
Try it on your own server
Create a free account and your API key is ready in about two minutes. 3 GB included, bandwidth never billed, no card needed.