# General Translation Platform: API keys
URL: https://generaltranslation.com/en-US/docs/platform/dashboard/reference/api-keys.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Create and manage project and Organization API keys for apps, local development, and automation. Reference for API keys.

API keys authenticate your apps, CLI, and automation with General Translation. Use the narrowest key scope that fits the workflow.

## Key scopes [#key-scopes]

General Translation supports two API key scopes:

- **Organization keys** for Organization-level automation. Use them for org-level automation or workflows that need to operate across projects in the Organization.
- **Project keys** for a single project. Use them in server environments, local development, and project-scoped tooling. Never include them in deployed browser or mobile app bundles.

In the Dashboard, both scopes support **All** or **Custom** permissions. **All** grants every permission you can delegate within that scope. **Custom** lets you select a smaller set; select at least one permission. You can only grant permissions you hold.

## Create Organization keys [#create-organization-keys]

Create Organization keys from **Organization > Developer > API Keys**. Organization keys use the `gtx-org-` prefix and can be configured with a custom permission set.

In these Dashboard controls, permissions are configured per resource. `Write` includes `Read`.

| Resource                | Read                                  | Write or enabled                                      |
| ----------------------- | ------------------------------------- | ----------------------------------------------------- |
| **Project creation**    | Not applicable                        | Create new projects in the Organization               |
| **Project API keys**    | View API keys for projects             | View, create, and delete project API keys             |
| **Files**               | Read project files and translations   | Upload source content and write translated files      |
| **Context**             | Read project and Organization context | Manage Context Groups, Glossary, and Custom Prompts    |
| **Organization assets** | Not applicable                        | Upload and replace assets, such as fonts, shared by every project in the Organization |
| **Runtime translation** | Not applicable                        | Translate content on demand                           |
| **Translation queue**   | Not applicable                        | Queue file translation jobs for background processing |
| **Project settings**    | Not applicable                        | Update project settings such as the default locale and CDN delivery |

Enable **Project creation** for automation that calls the [Create a project](/docs/platform/openapi/reference/projects/create-project) endpoint. Its `org:projects:create` permission also allows creation with CDN delivery enabled; **Project settings** (`project:write`) is needed only for later settings updates. Grant each key only the permissions it needs.

Set **Context** to **Read** or **Write** for automation that calls the [Context Management API](/docs/platform/openapi/reference/context-groups/list-context-groups) (`org:context:read` / `org:context:write`). An Organization key with this permission can act on every Context Group in the Organization. A [project key](#create-project-keys) reaches only the groups assigned to its project, and cannot create, update, delete, assign, or unassign a group.

Set **Organization assets** to **Write** for automation that uploads fonts for Lottie translation, such as the CLI [`fonts`](/docs/cli/reference/config#fonts) sync (`org:assets:write`). Project keys cannot upload fonts.

Set **Project API keys** to **Write** for automation that calls [Create a project API Key](/docs/platform/openapi/reference/api-keys/create-project-api-key) or [Delete a project API key](/docs/platform/openapi/reference/api-keys/delete-project-api-key). **Read** is enough to [list](/docs/platform/openapi/reference/api-keys/list-project-api-keys) or [get](/docs/platform/openapi/reference/api-keys/get-project-api-key) a project's keys, which never returns their secrets. Use an Organization key with the required permissions for a project in that Organization. Project keys cannot list, create, or delete keys.

When creating keys through the [HTTP API](/docs/platform/openapi/reference/api-keys/create-project-api-key), select permissions explicitly or omit the selection to grant all project permissions you can delegate. Unlike the Dashboard controls, explicit HTTP Write grants do not include Read.

## Create project keys [#create-project-keys]

Create project keys from **Project > API Keys**. New keys start with `gtx-api-` and work in development, staging, and production. Their permissions determine which operations they can perform.

1. Create a key and enter a descriptive **Name**.
2. Under **Permissions**, choose **All** or **Custom**.
3. For **Custom**, select the access each resource needs.
4. Select **Create**, then copy the full key immediately. Store it in environment variables or a secrets manager.

Project keys support these resources:

| Resource | Read | Write or enabled |
| --- | --- | --- |
| **Files** | Read project files and translations | Upload source content and write translated files |
| **Context** | Read the Context Groups assigned to the project | Generate context, and edit and reorder the Context Groups assigned to the project |
| **Runtime translation** | Not applicable | Translate content on demand |
| **Translation queue** | Not applicable | Queue file translation jobs |
| **Project settings** | Not applicable | Update project settings |

With **Context**, a project key can call the [Context Management API](/docs/platform/openapi/reference/context-groups/list-context-groups) for the Context Groups assigned to its project. **Read** (`project:context:read`) lists those groups and reads and exports their Glossary and Custom Prompts. **Write** (`project:context:write`) also edits and imports that content, reorders the groups, and generates context. A project key cannot create, update, delete, assign, or unassign a Context Group; those actions need an Organization key. A group that is not assigned to the key's project returns the same `403` as a group that does not exist.

For local on-demand translation, any project key with `project:translations:generate` works, including a full-access key. To minimize risk, we recommend a separate key with **Custom** permissions: set **Runtime translation** to **Enabled** and leave the other resources at **None**. For a file translation pipeline, grant **Files > Write** (which includes Read), **Translation queue > Enabled**, and **Context > Write**. [`gt translate`](/docs/cli/reference/commands/translate) generates context before it queues translations, so it fails without **Context > Write**. When you create the key through the HTTP API or [`gt api-key create`](/docs/cli/reference/commands/api-key-create) instead, request `project:files:read`, `project:files:write`, `project:translations:enqueue`, and `project:context:write` explicitly, because Write does not include Read there.

The SDK setting `devApiKey` and environment variable `GT_DEV_API_KEY` still enable development translation and hot reload. Supply a project key with runtime translation permission in that setting. The setting name does not indicate a separate key type.

In most SDK and CLI workflows, use the key with your project ID:

```bash
GT_API_KEY=gtx-api-...
GT_PROJECT_ID=...
```

For account-based CLI access, use [`gt login`](/docs/cli/reference/commands/login). To create a project key with explicit permissions from the CLI, use [`gt api-key create`](/docs/cli/reference/commands/api-key-create).

## Manage keys [#manage-keys]

Use descriptive names so keys are easy to identify later.

Open the key list for the project or Organization to review existing keys. The key list shows:

- **Name** and **Key**, including a truncated key for identification
- **Permissions**, for both project and Organization keys
- **Created**, when the key was generated
- **Last Used**, when the key was last used

With permission to manage keys, use **Edit key** to rename a key or update its permissions, and **Delete** to revoke it. The full secret is shown only when the key is created.

Revoke keys that are no longer used, and create replacements when rotating credentials. A deleted key usually stops authenticating at once, and always within 10 minutes.

To rotate a project key from automation, [create](/docs/platform/openapi/reference/api-keys/create-project-api-key) the replacement, switch your workflow to it, then [delete](/docs/platform/openapi/reference/api-keys/delete-project-api-key) the old key by its ID. Both calls need an Organization key with **Project API keys** set to **Write**.

## Existing development keys [#existing-keys]

Existing `gtx-dev-` keys continue to authenticate as project keys. Keys with the old default runtime-only permission now receive the default project permissions, including files, context, translation queue, and project settings. Other custom permission sets are preserved.

Review existing keys in **Project > API Keys**. For local development, we recommend restricting them to **Runtime translation** or replacing them with new runtime-only keys. Full-access keys still work, but a `gtx-dev-` prefix no longer means limited permissions. Never include these keys in deployed client bundles.

## Security practices [#security-practices]

- Never commit keys to source control.
- Never include any API key in deployed browser or mobile app bundles, regardless of its permissions. Keep deployed credentials in server-side environment variables or a secrets manager.
- API keys can be used in client code served only by your local development server. Full-access project keys work, but we recommend restricting local development keys to **Runtime translation** (`project:translations:generate`) to minimize risk.
- Store keys in environment variables or a secrets manager.
- Use separate keys for development, staging, and production.
- Rotate keys periodically.
- Revoke unused keys.
- Prefer the narrowest scope that works for the integration.

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.