Skip to main content
Authenticate every request with an API key in the Authorization header, using the Bearer scheme:
Keys belong to one company. The company is resolved from the key alone, so no request ever names a company, and a key can never read another company’s data.

​
Live and test keys

Build and test against a tb_test_ key, then swap in the tb_live_ key at go-live; nothing else changes. GET /v1/ping reports a key’s mode, so a deployment can assert it is using the key it expects.

​
Getting a key

TeamBuilder issues keys during onboarding. Email contact@teambuilder.ge with your company name, the scopes you need and a technical contact.
  • A key is shown once, when it is issued. TeamBuilder stores only a hash of it, so a lost key cannot be recovered; ask for a new one.
  • A company normally holds one live and one test key. A second key per mode is issued only for a rotation.
  • A key may carry an expiry date. An expired key behaves like a revoked one.

​
Scopes

Each key carries a set of scopes. A request to an endpoint whose scope the key lacks returns 403 forbidden. GET /v1/ping works with any valid key, whatever its scopes.
leaderboard:read also reveals your active department names, because the by-department leaderboard lists every department. Ask for a key without it if a consumer must not see your structure.
Ask for the narrowest set each integration needs. An intranet widget needs only the read scopes it renders; only the system that runs your roster sync needs employees:write, ideally on a key of its own.

​
401 or 403?

​
Storing keys

Call the API from your backend, never from a browser or a mobile app. The API does not accept cross-origin browser requests, so browser calls fail by design.
Load keys at runtime from your secret manager (AWS Secrets Manager, Azure Key Vault, GCP Secret Manager, HashiCorp Vault, Doppler, or your platform’s encrypted variables). Never commit a key or bake it into an image.
The prefixes make leaked keys easy to detect. Add a custom pattern to your secret scanner:
If a key leaks, email contact@teambuilder.ge so it can be revoked at once, then rotate.
Redact the Authorization header in request logging and APM tools. TeamBuilder never logs key material; quote the request_id instead when you need help with a request.

​
Rotating a key

Rotation needs no downtime: both keys stay valid until the old one is revoked.
1

Request a new key

Ask contact@teambuilder.ge for a replacement with the same scopes.
2

Deploy it

Put the new key in your secret manager and roll it out to every service that calls the API.
3

Verify

Call GET /v1/ping from each service and check mode and scopes.
4

Revoke the old key

Ask for the old key to be revoked. From then on it returns 401.
Rotate on a schedule that suits your security policy, at once when someone with access to a key leaves, and immediately if a key may have leaked.