Skip to content
docs

API Authentication

All Comvi API endpoints require authentication. Choose the method that fits your use case.

API Keys

Section titled “API Keys”

Best for: Server-to-server integrations, CI/CD pipelines, CLI tools, and automated scripts.

Creating an API Key

Section titled “Creating an API Key”
  1. Log into app.comvi.io
  2. Go to Settings > API Keys
  3. Click Create API Key
  4. Give it a name and select the scopes it needs
  5. Copy the key — it’s only shown once

Using an API Key

Section titled “Using an API Key”

Pass the key in the X-API-Key header:

Terminal window
curl -X GET \
  -H "X-API-Key: tlk_your_api_key_here" \
  https://api.comvi.io/api/v1/projects

In the Comvi CLI, set it in .comvirc.json or as an environment variable:

Terminal window
export COMVI_API_KEY=tlk_your_api_key_here
comvi pull

API Key Permissions

Section titled “API Key Permissions”

API keys can be scoped to specific API capabilities:

ScopeDescription
project:readRead project metadata, locales, and namespaces
translations:readRead and export translation keys and values
translations:writeCreate and update translation keys, values, namespaces, and imports
schema:readRead key schema/type-generation metadata

Key Security

Section titled “Key Security”
  • API keys start with tlk_ for easy identification
  • Store keys in environment variables, never in source code
  • Rotate keys periodically and revoke unused ones
  • Each key logs its last usage time in the dashboard

Session Authentication

Section titled “Session Authentication”

Best for: Browser-based access (used by the Comvi dashboard).

Sessions are established by signing in through the /api/v1/auth/signin endpoint. The server returns a session cookie that authenticates subsequent requests.

CSRF Protection

Section titled “CSRF Protection”

Session-authenticated requests that modify data (POST, PUT, PATCH, DELETE) require a CSRF token:

  1. Get the CSRF token from a GET request to any authenticated endpoint (returned in a cookie)
  2. Include it in the X-CSRF-Token header on mutating requests
Terminal window
curl -X POST \
  -H "Cookie: session=..." \
  -H "X-CSRF-Token: your-csrf-token" \
  -H "Content-Type: application/json" \
  -d '{"name": "New Project"}' \
  https://api.comvi.io/api/v1/projects

Error Responses

Section titled “Error Responses”

401 Unauthorized

Section titled “401 Unauthorized”

Missing or invalid authentication credentials.

{
  "statusCode": 401,
  "error": "UNAUTHORIZED",
  "message": "Invalid or missing authentication"
}

403 Forbidden

Section titled “403 Forbidden”

Valid credentials but insufficient permissions.

{
  "statusCode": 403,
  "error": "FORBIDDEN",
  "message": "You do not have permission to perform this action",
  "meta": {
    "requiredPermission": "translations:write"
  }
}

Next Steps

Section titled “Next Steps”