Authentication and API keys
The public verification calls need no credentials. Everything under https://app.tanba-ooh.kz/api/v1 needs an API key or a console session.
Create a key
An administrator of an operator or authority organisation opens Integrations in the console and creates a key. The secret has the form
tnbk_<prefix>_<secret>and is shown once. The platform keeps only a hash of it, so a lost key cannot be recovered: revoke it and create another.
Send the key
curl -H 'Authorization: Bearer tnbk_EXAMPLE_secret' https://app.tanba-ooh.kz/api/v1/structures?limit=10The same routes also work with a console session cookie. A call that changes data must then carry the X-Tanba-CSRF header.
Scopes
| Scope | Allows |
|---|---|
read:approvals | Approvals, their manifests, media and envelopes, approvals as CSV |
read:structures | Structures and their CSV export |
read:stats | The operational report and its CSV sections |
read:billing | Billing periods, the money report and its CSV sections |
read:creatives | Look creative files up by their hash |
read:inventory | The screens of the market with their sellers and OpenRTB fragments |
write:submissions | Create a submission and upload its media, nothing else |
write:plays | Report plays from your own CMS; operator administrators only. Ad platform administrators send claims of served plays with it and read their verification |
relay:commands | Fetch and acknowledge the signed commands of a CMS installation; operator administrators only |
Each operation page names the scope it needs.
What a key can never do
- A key can only hold scopes that the person who created it holds, and at every call it acts with that person's current rights in the organisation. If the person is demoted or leaves, the key shrinks or stops.
- A key never reaches key management, webhook management, user management, moderation or approval decisions. These stay with people in the console.
- Keys hold scopes, not roles. Nothing in the API grants a role.
Errors
| Status | code | Meaning |
|---|---|---|
| 401 | invalid_api_key | The key is unknown, revoked or malformed |
| 401 | unauthenticated, session_expired | No valid session |
| 403 | key_scope_denied | The key lacks the scope this call needs |
| 403 | key_route_denied | No key may call this route |
| 429 | rate_limited | Too many requests; wait for Retry-After |
Creating a key, revoking it and every refused call of a valid key are written to the audit log of your organisation.