Open API v1
Authentication
Every /open/v1 request except the OpenAPI spec requires a bearer API key.
Authorization: Bearer tg_live_...
Missing, revoked, expired, or unknown keys return 401 with code: invalid_api_key.
Scopes
A key can only call endpoints it was granted. Missing a scope returns 403 with code: insufficient_scope.
| Scope | Access |
|---|---|
contacts:read | List and retrieve contacts |
contacts:write | Create, update, and delete contacts |
tickets:read | List and retrieve tickets |
tickets:write | Create, update, and delete tickets |
conversations:read | List conversations and their messages |
messages:write | Send a message or internal note |
webhooks:manage | Create and delete webhook endpoints |
Create a separate key per integration and grant only the scopes it needs.
Rotation and revoke
In Settings → Developer:
- Rotate issues a new secret immediately. The old secret stops working. Store the new value; it is shown once.
- Revoke disables the key. Integrations using it will start getting
401.
Test vs live
The environment on a key is live or test. It is metadata for your own bookkeeping. Both talk to the same workspace data. Prefer a test key while you build, then create a live key for production.
Legacy bot keys
Older sk-... keys from Legacy bot key still work on /open/v1 and /v2/* during the deprecation window. They have every scope and cannot be limited.
/v2/* responses include:
Deprecation: true
Link: <https://developers.taggoai.com/authentication>; rel="deprecation"
Move new integrations to a scoped tg_live_ / tg_test_ key and /open/v1.