Authentication and scopes
Authenticate AI Glot API requests with workspace keys or OAuth tokens, choose minimum scopes and rotate credentials without exposing secrets.
Send a workspace API key or OAuth access token as a bearer credential:
Authorization: Bearer aig_live_••••••••Never place a credential in a query string. URLs are copied into logs, browser history and referrer headers.
Workspace API keys
An admin creates keys in Developer tools, on the API tab. The complete secret is shown once; AI Glot stores only a protected hash. Up to 10 keys may be active in a workspace.
- Name. Describe the integration that will use the key, for example the CI job or service. Use a separate named key for each integration.
- Permissions. Pick a preset: Read only, Glossary manager or Full access. Open Advanced to tick individual scopes instead. Start from the smallest set the integration needs.
- Expiry. Choose No expiry, or an expiry in 30, 90 or 365 days.
- Create key. The complete secret appears once, right after creation. Copy it then; it cannot be shown again.
Rotating a key
The key list offers a Rotate action. It issues a replacement with the same name, scopes and expiry, then revokes the original in the same operation. The old key stops working immediately, is marked replaced rather than plainly revoked, and records which key succeeded it.
That is deliberate: you rotate because a secret may be compromised, and a key that keeps working for another hour keeps working for whoever took it. For a planned, zero-downtime handover, create a second key instead, move the integration onto it, confirm the old key is quiet, then revoke it.
OAuth tokens
The CLI and compatible MCP clients can use OAuth 2.1. OAuth is recommended for a person because the connection records who approved it and respects that member’s access ceiling. API keys remain the right fit for CI and backend services.
Scopes
These scopes work today:
| Scope | Allows |
|---|---|
account:read | Workspace identity, plan, capabilities, limits and credit summary |
usage:read | Usage totals and time buckets |
batches:read | List translations, inspect progress and download completed results |
batches:create | Create a translation, plan it and approve it. Approval spends workspace credits |
batches:write | Rename and archive translations, and cancel one that is running. Cancelling charges for the work already completed |
glossaries:read | List and retrieve glossaries |
glossaries:write | Create, update, replace or delete glossaries |
A missing scope returns 403 insufficient_scope.
Reserved scope
One more scope can be granted today but no endpoint honours it yet. It appears on the OAuth consent screen and in the dashboard’s Full access preset, so it is documented here rather than hidden: a permission you are asked to approve should always be findable in the reference.
| Scope | Will allow | Status |
|---|---|---|
webhooks:write | Create, edit and delete the webhooks that notify your systems when work finishes | Not available yet |
It exists early so that a credential granted now keeps working the day the capability ships, without a second approval round. Read capabilities on GET /v1/account rather than the granted scopes to decide what a credential can actually do. A scope can be held before the endpoint behind it exists. Uploading a file needs no scope of its own: files are sent with the create call, under batches:create.
Member ceiling
Workspace admins can limit developer access for members. An OAuth client receives the intersection of what it requested and what the approving member may use. Reconnecting with a broader request cannot bypass a read-only ceiling.
A new workspace’s default member ceiling includes every scope, batches:create too. A member can already start a translation in the web app, so the ceiling matches what they can do there. Workspaces created before 31 August 2026 keep the ceiling they had, which left batches:create out. The one scope that spends credits deserves a deliberate choice: an agent looping with a delegated credential could consume a whole month’s allowance before anyone noticed, and credits cannot be un-spent. An admin can untick it, or any other scope, in the Permissions tab of Developer tools, or for one person from the Team page.