# General Translation Platform: API keys
URL: https://generaltranslation.com/en-GB/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:

* **Organisation keys** for Organisation-level automation. Use them for org-level automation or workflows that need to operate across projects in the Organisation.
* **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 Organisation keys [#create-organization-keys]

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

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 Organisation                             |
| **Project API keys**    | View API keys for projects            | View and create project API keys                                    |
| **Files**               | Read project files and translations   | Upload source content and write translated files                    |
| **Context**             | Read project and Organisation context | Manage Context Groups, Glossary, and Custom Prompts                 |
| **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/project/create-project) endpoint. Its `org:projects:create` permission also allows projects to be created with CDN delivery enabled; **Project settings** (`project:write`) is only needed for subsequent 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-management/list-groups) (`org:context:read` / `org:context:write`). Project keys cannot manage Context Groups.

Set **Project API keys** to **Write** for automation that calls [Create a project API Key](/docs/platform/openapi/reference/project/create-api-key). Use an Organisation key with the required permissions for a project in that Organisation. Project keys cannot create other keys.

When creating keys through the [HTTP API](/docs/platform/openapi/reference/project/create-api-key), select permissions explicitly or omit the selection to grant all project permissions you are able to 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 project context                | Manage project context                           |
| **Runtime translation** | Not applicable                      | Translate content on demand                      |
| **Translation queue**   | Not applicable                      | Queue file translation jobs                      |
| **Project settings**    | Not applicable                      | Update project settings                          |

For local on-demand translation, any project key with `project:translations:generate` works, including a full-access key. To minimise 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** and **Translation queue > Enabled**; add **Context > Write** if the pipeline generates context.

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 Organisation to review existing keys. The key list shows:

* **Name** and **Key**, including a truncated key for identification
* **Permissions**, for both project and Organisation 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.

## 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 minimise 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.