Authentication
Authenticate API requests with a project deploy token and give it only the abilities the job needs.
Every /v1 request authenticates with a deploy token sent as a bearer token. The token belongs to one project, and the project it belongs to is the project the request acts on.
curl https://api.transglot.ai/v1/project \
-H "Authorization: Bearer $TRANSGLOT_TOKEN"Deploy tokens
Owners and admins mint deploy tokens in the console under Settings → Developer → API tokens. See Create a deploy token for the steps.
- Send the whole value. A token looks like
42|tgl_followed by a random string. The number before the|is part of the credential. - Shown once. The value appears once, at creation, and is stored hashed. If you lose it, revoke it and mint another.
- Project-owned. A token keeps working after the person who minted it leaves the workspace. Revoke it explicitly; revoking takes effect on the next request.
- Expiry. Choose Never expires, 30 days, 90 days or 365 days. An expired token is refused with
401, like a revoked one. - Limited to your own access. You can only give a token abilities you hold yourself on that project.
transglot issues two other credentials that are not API tokens and do not work against /v1:
| Credential | Looks like | What it can do |
|---|---|---|
| Deploy token | 42|tgl_... | Call the API with the abilities it was given |
| CDN key | taicdn_... | Read this project's published bundles from GET /v1/cdn/..., sent as X-Transglot-Cdn-Key or ?key=. Nothing else |
| Publishable key | taip_... | Open the in-context editor in a browser. See Publishable keys |
Abilities
A token carries one or more of five abilities. Each endpoint requires one, and abilities do not include each other: a manage token cannot read the glossary unless it also has read.
| Ability | Grants |
|---|---|
push | Upload locale files |
pull | Download locale files |
manage | Start and stop paid work (translation runs, quality checks, glossary extraction), publish to the CDN, and change project configuration (glossary terms, webhooks) |
read | Read single translation values and the glossary |
write | Write single translation values |
Ability per endpoint
| Endpoint | Ability |
|---|---|
GET /v1/project | any of push, pull, manage |
POST /v1/push | push |
GET /v1/pull | pull |
POST /v1/translate | manage |
GET /v1/batches | any of push, pull, manage |
GET /v1/batches/{batch} | any of push, pull, manage |
POST /v1/batches/{batch}/retry-failed | manage |
POST /v1/batches/{batch}/cancel | manage |
GET /v1/translations | read |
POST /v1/translations/batch | read |
PUT /v1/translations | write |
POST /v1/qa/run | manage |
POST /v1/cdn/publish | manage |
GET /v1/glossary, GET /v1/glossary/export | read |
POST /v1/glossary, PUT and DELETE /v1/glossary/{termId}, POST /v1/glossary/import, POST /v1/glossary/extract | manage |
GET /v1/webhooks, GET /v1/webhooks/events, GET /v1/webhooks/events/{event}/sample | any of push, pull, manage |
POST /v1/webhooks, DELETE /v1/webhooks/{webhook} | manage |
A CI job that only syncs files needs push and pull. Give manage only to the jobs that start paid work or change configuration: it is the difference between a leaked token that can read strings and one that can start translation runs.
401: not authenticated
A missing, malformed, unknown, revoked or expired token gets 401:
{
"type": "/problems/unauthenticated",
"title": "Unauthenticated",
"status": 401,
"detail": "Unauthenticated."
}The answer is the same for every reason, so a 401 never tells anyone whether a token existed. Check that the header is Authorization: Bearer <token>, that you sent the whole value including the number and |, and that the token has not expired.
403: authenticated but refused
A 403 means the token is valid and the request was refused. Branch on type:
type | Why | What to do |
|---|---|---|
/problems/missing-ability | The token lacks the ability the endpoint requires. ability names it | Mint a token with that ability |
/problems/plan-feature-required | The account's plan does not include API access | An account owner upgrades the plan; the same token then works |
/problems/plan-limit | The endpoint needs a plan feature the account does not have, for example quality checks | An account owner upgrades the plan |
/problems/ai-paused, /problems/workspace-read-only, /problems/workspace-closed | The workspace's standing refuses this kind of request | An account owner resolves it in the console |
{
"type": "/problems/missing-ability",
"title": "Missing ability",
"status": 403,
"detail": "The token is missing a required ability.",
"ability": "manage"
}For an endpoint that accepts any of push, pull or manage, ability names the first of them, push.
A 403 does not clear by waiting, so do not retry it. Errors lists every problem type.