Deploy tokens
Create the project token that the CLI, the GitHub Action, the REST API and the MCP server authenticate with, give it only the abilities the job needs, and revoke it when it is done.
A deploy token is a secret that authenticates one project. The CLI, the GitHub Action, the REST API, the MCP server and the language server all use one. Tokens start with tgl_, and the console calls them API tokens.
A token belongs to the project, not to the person who created it. Removing that person from the workspace does not revoke their tokens; revoke them explicitly. The token list shows who created each one.
Before you start
- Role. Admins can create and revoke tokens, as can members whose custom role includes Create and revoke API tokens.
- Plan. Tokens work on plans with API access, Starter and above. See pricing. If the account moves to a plan without it, tokens stay saved and work again after an upgrade.
Abilities
Each token carries one or more abilities, and every API request checks them. Give a token only what its job needs: a leaked token that can only pull reads strings, while one with manage can start translation runs that use your word allowance.
| Ability | What it allows | Used by |
|---|---|---|
push | Upload source files and existing translations. Price and start the first translation run of a new project. | transglot push, transglot init |
pull | Download translated files. | transglot pull |
manage | Start, retry and cancel translation batches, run quality checks, publish to the CDN, change the glossary, and create or delete webhook endpoints. | transglot cancel, the MCP server's batch, quality and glossary tools |
read | Read single translations and the glossary. | The MCP server, your own scripts |
write | Write single translations. With read, it also lets your backend authorize the in-context editor. | The MCP server, your own backend |
Any one of push, pull or manage also lets a token read the project's details and its batches, which transglot status and every --wait need.
New tokens start with push and pull selected, which is what the CLI and the GitHub Action need. Add manage only for a job that cancels batches or starts translation runs itself.
A token carries no language restriction and no role, so you can only give it access you hold on the project yourself. If your access is narrower, some abilities are not offered and the dialog says: "Some abilities are not listed: a token carries no language scope and no role, so it can only be given access you hold on this project yourself. An admin can mint the rest."
Create a token
Open Developer settings
Open the project, then Settings → Developer. Under API tokens, select New token.
Fill in the dialog
The Create API token dialog asks for three things:
- Name: where the token will live, such as
ci-deploy(up to 100 characters). - Abilities: one or more of
push,pull,manage,readandwrite. - Expiry: Never expires, 30 days, 90 days or 365 days.
Select Create token.
Copy the value
Copy your new API token shows the token once: "This token is shown only once. Store it in your CI secrets now. It cannot be recovered later." Select Copy, store it, then select Done.
transglot keeps only a hash of the token, so nobody can show it to you again. If you close the dialog without copying, revoke the token and create another.
Store the token
Every transglot tool reads the token from the TRANSGLOT_TOKEN environment variable:
| Tool | Where the token goes |
|---|---|
| CLI in CI | A CI secret exposed as TRANSGLOT_TOKEN. See Use the CLI in CI. |
| GitHub Action | A repository secret named TRANSGLOT_TOKEN, passed to the action's token input. See The GitHub Action. |
| MCP server | The TRANSGLOT_TOKEN entry in your MCP client's configuration. |
| REST API | The Authorization: Bearer <token> header. See Authentication. |
Never commit a token to transglot.json or to a workflow file.
On a laptop you rarely need to create a token by hand: transglot init signs you in through the browser and creates a token with push and pull, named after your machine. It is listed with the project's other tokens.
Track and revoke tokens
The API tokens list shows each token's name and creator, its abilities, when it was last used, and when it expires (never for tokens without an expiry). The project's Releases page also charts calls per token over the last 14 days under Token usage, in its Connect & SDK view.
To revoke a token, select Revoke on its row. The confirmation explains: "Any CLI or CI job authenticating with this token starts failing on its next run. The token value cannot be recovered, so a replacement has to be created and stored again." Type the token's name to continue, then select Revoke token. Revoking takes effect immediately.
To rotate a token without downtime, create the replacement first, update the secret everywhere it is used, then revoke the old one.
Other credentials
A project has three other kinds of credential. They are created on the same Developer settings page, and none of them can replace a deploy token.
| Credential | Looks like | Secret? | What it is for |
|---|---|---|---|
| Deploy token | tgl_… | Yes, shown once | The CLI, the GitHub Action, the REST API and the MCP server. |
| Publishable key | taip_… | No. Safe to embed in client JavaScript, limited to the origins you allow, and listed so you can copy it again. | Loading the in-context editor SDK in your app. |
| CDN key | taicdn_… | Yes, shown once | Read-only access to a project's published runtime bundles. |
| Webhook signing secret | Yes, shown once | Verifying that a webhook delivery came from transglot. |
See Project developer settings for the whole page.