Authentication
Every request except the health check and the OpenAPI document needs an API key.
Create a key
Owners and admins can create keys on the Starter and Enterprise plans.
Open API keys
In Teambrite, go to Settings, Developer, then API keys.
Create the key
Choose New key, name it after what will use it, and choose what it can do. You may be asked to confirm it's you.
Copy it somewhere safe
The full key is shown only once. Keys start with tb_live_. Keep yours in a secrets manager, and never put it in code that runs in a browser.
Scopes
A key can only do what it was given when it was created. To change that, create a new key and revoke the old one.
| Scope | What it allows | Personal data it can see |
|---|---|---|
program:read | List programs | None |
employee:read | List employees and list groups | Full name, work email, start date, birthday month and day unless private, picture, time zone, and the ID from your own system |
employee:write | Create and update employees | The profile of each employee it adds or changes, as employee:read shows it |
group:write | Create, update and archive groups, and add or remove members | None |
reward:read | Upcoming rewards and the insights | Full name, start date, reward dates and when someone was last rewarded |
metric:write | Send a metric value and see how it was checked | The metric values your company sent |
Teambrite never keeps a birth year, so none of these can show one. reward:read lists the date each reward is due, so a birthday reward shows when someone's birthday is, even if they've made it private. Give that scope only to systems that should see it.
The two write scopes change who gets rewarded and when. employee:write sets the email rewards are sent to and the dates programs pay on, and group:write decides who programs that target a group reach. Every change a key makes is in your audit log under the key's name.
A key without the scope an endpoint needs gets a 403 with the code API_KEY_SCOPE_MISSING. Keys created before scopes existed have metric:write only.
Send the key
Pass it as a bearer token:
curl https://api.teambrite.com/v1/programs \
-H "Authorization: Bearer $TEAMBRITE_API_KEY"
A key belongs to one company. Nothing in a request names a company, so every call acts on the company that owns the key.
Revoke a key
Choose Revoke next to the key on the same page. Anything using it stops working right away, and this can't be undone.
If your plan changes
If your company leaves a plan with API access, requests get a 403 with the code PLAN_UPGRADE_REQUIRED. Your keys are kept, and they work again when you return to a plan that includes the API.