API keys

An API key authenticates automation: comvi push and comvi pull, CI pipelines, type generation, and any server-to-server call against the REST API. Loading deployed translations into an app needs no key, because the CDN is unauthenticated.

Terminal

curl -H "Authorization: Bearer comvi_…" https://api.comvi.io/v1/project

Pass the key as a Bearer token in the Authorization header. GET /v1/project returns the project the key belongs to and is the first call for any integration. The base path is /v1. Bearer requests need no CSRF token.

How a key is checked

On every request Comvi checks that the key exists and is active, has not expired, that its creator’s account is still active with access to the project, that the key’s scopes still fall inside the creator’s current permissions, and that what remains covers the permission the endpoint requires. A key never outgrows its creator: demote the creator and the key’s access shrinks on the next request; delete, block or remove them from the project and the key stops working; if nothing survives the intersection, the request fails with 401 API_KEY_PERMISSIONS_REVOKED. History entries attribute actions to the key’s name.

Keys are project-scoped and cannot reach organization-scoped routes. A route that accepts either auth method refuses a key with 403 FORBIDDEN and “API keys cannot access organization-scoped routes”; a session-only route never reads the header and answers 401 AUTHENTICATION_REQUIRED. Managing members, organization settings or billing needs a signed-in person. Authentication lists the split per route.

Scopes

Scope	Grants
project:read	Read the project, its locales and its namespaces
translations:read	Load translations, pull and export data, read keys, comments, history, glossary and TM
translations:write	Create, update, import and edit keys, values, namespaces, locales, glossary entries and comments; delete a namespace; edit the project’s name, description and AI context
translations:review	Mark translations reviewed
translations:delete	Soft-delete translation keys
schema:read	Read the type-generation schema

project:read is added automatically to every key and does not appear in the dashboard’s scope list; the SDK, the CLI and the in-context editor all start from GET /v1/project. At least one scope is required, and you can only grant what you hold: a request for a scope your own permissions do not cover fails with API_KEY_FORBIDDEN_PERMISSIONS.

The create dialog offers presets:

Preset	Scopes
Runtime SDK	translations:read
CLI pull	translations:read
CLI push/import	translations:read, translations:write
In-context editor	translations:read, translations:write
Type generation	schema:read
MCP automation	translations:read, translations:write, translations:review

Create a key

1. Open Settings → API Keys in the project sidebar.

2. Click Create API Key and name it after the consumer, such as github-actions-release. The name shows up in logs and in Last Used.

3. Pick a preset or tick the scopes you need.

4. Copy the key. It is shown once, and cannot be viewed again after the dialog closes. Keys start with comvi_ so secret scanners can spot them.

The dashboard offers the six scopes as checkboxes and has no expiry field. To change what a key can do, create a new one and delete the old one. The REST API accepts expiresAt on create and update, and an expired key fails with 401 API_KEY_EXPIRED.

Use a key

CLI

Terminal

export COMVI_API_KEY=comvi_…
comvi pull

GitHub Actions

.github/workflows/translations.yml

- run: npx --package @comvi/cli comvi pull
  env:
    COMVI_API_KEY: ${{ secrets.COMVI_API_KEY }}

GitLab CI

.gitlab-ci.yml

sync-translations:
  script:
    - npx --package @comvi/cli comvi pull
  variables:
    COMVI_API_KEY: $COMVI_API_KEY

The CLI reads COMVI_API_KEY from the environment. The config file can also hold apiKey, but the file then has to stay out of git, so prefer the environment variable and keep .comvirc.json committable. See CI/CD integration for complete pipelines.

Rotate a key

1. Create a new key with the same scopes.

2. Update every consumer: CI secrets, deployed services, local .env files.

3. Trigger one job or request to confirm the new key works.

4. Delete the old key in the dashboard. It stops working immediately.

Rotate on a schedule, after someone leaves the team, or on a suspected leak. Last Used on each key tells you whether anything still depends on it before you delete it.

A leaked key

Delete it immediately and create a replacement. Check Last Used and the project history for unexpected activity, and rotate any downstream credentials the leak may have exposed.

Practices

• Keep keys in environment variables or a secrets manager; never commit them.
• One key per integration, with the narrowest preset that works. translations:read is enough for pulls and the runtime SDK.
• Replace a departing colleague’s keys. They keep working only as long as that account and its permissions do.

Troubleshooting

• 401 Unauthorized. Check that the header is Bearer followed by the whole token and that the key is still listed under Settings → API Keys. Code API_KEY_PERMISSIONS_REVOKED means the key is fine but its creator no longer holds any of the permissions behind its scopes.
• 403 Forbidden. The key lacks the scope the endpoint requires. Create a replacement key with the missing scope. “API keys cannot access organization-scoped routes” means no scope will help; that route needs a signed-in person.
• The key is not listed. Keys are project-scoped. Switch to the project it was created in.

Next steps

Roles & permissionsThe permission catalog scopes map onto.

REST API authenticationHeader format and error codes per endpoint.

CLIConfigure the CLI with an API key.

CI/CD integrationFull pipeline examples.