API Keys

API keys provide server-to-server authentication for the Comvi API. Each key is scoped to a specific project and can be restricted to a set of API scopes.

List API keys

Returns all API keys for a project. The actual key value is never returned after creation – only the key prefix is shown for identification.

GET /api/v1/projects/:projectId/api-keys

Path parameters

Parameter	Type	Required	Description
`projectId`	`integer`	Yes	Project ID

Example request

curl -X GET \
  -H "Authorization: Bearer comvi_your_api_key" \
  https://api.comvi.io/api/v1/projects/5/api-keys

Example response

[
  {
    "id": 1,
    "projectId": 5,
    "name": "CI/CD Pipeline",
    "description": "Used by GitHub Actions for pulling translations",
    "keyPrefix": "comvi_a1b2",
    "lastUsedAt": "2025-03-20T14:00:00Z",
    "expiresAt": null,
    "isActive": true,
    "permissions": ["project:read", "translations:read", "schema:read"],
    "createdAt": "2025-01-15T10:00:00Z",
    "updatedAt": "2025-01-15T10:00:00Z"
  }
]

Response fields

Field	Type	Description
`id`	`integer`	API key ID
`projectId`	`integer`	Project this key belongs to
`name`	`string`	Descriptive name for the key
`description`	`string \| null`	Optional description
`keyPrefix`	`string`	First characters of the key for identification (e.g., `comvi_a1b2`)
`lastUsedAt`	`string \| null`	ISO 8601 timestamp of last usage, or `null` if never used
`expiresAt`	`string \| null`	Expiration date, or `null` for non-expiring keys
`isActive`	`boolean`	Whether the key is currently active
`permissions`	`string[]`	List of API scopes granted to this key
`createdAt`	`string`	ISO 8601 creation timestamp
`updatedAt`	`string`	ISO 8601 last update timestamp

Create API key

Create a new API key for a project. The full key value is returned only in the creation response – store it securely.

POST /api/v1/projects/:projectId/api-keys

Path parameters

Parameter	Type	Required	Description
`projectId`	`integer`	Yes	Project ID

Request body

Field	Type	Required	Description
`name`	`string`	Yes	Descriptive name (1-255 characters)
`description`	`string`	No	Optional description (up to 2000 characters)
`expiresAt`	`string`	No	ISO 8601 expiration date
`permissions`	`string[]`	No	API scopes to grant. If omitted, Comvi derives the scopes the creating user can grant for this project.

Available API scopes

Scope	Description
`project:read`	Read project metadata, locales, and namespaces
`translations:read`	Read and export translation keys and values
`translations:write`	Create and update translation keys, values, namespaces, and imports
`schema:read`	Read key schema/type-generation metadata

Example request

curl -X POST \
  -H "Authorization: Bearer comvi_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI/CD Pipeline",
    "description": "Used by GitHub Actions",
    "permissions": ["project:read", "translations:read", "schema:read"]
  }' \
  https://api.comvi.io/api/v1/projects/5/api-keys

Example response

{
  "id": 2,
  "projectId": 5,
  "name": "CI/CD Pipeline",
  "description": "Used by GitHub Actions",
  "keyPrefix": "comvi_x9y8",
  "lastUsedAt": null,
  "expiresAt": null,
  "isActive": true,
  "permissions": ["project:read", "translations:read", "schema:read"],
  "createdAt": "2025-03-25T10:00:00Z",
  "updatedAt": "2025-03-25T10:00:00Z",
  "token": "comvi_x9y8z7w6v5u4t3s2r1q0p9o8n7m6l5k4"
}

Revoke API key

Permanently delete an API key. Any requests using this key will immediately start returning 401 Unauthorized.

DELETE /api/v1/api-keys/:id

Path parameters

Parameter	Type	Required	Description
`id`	`integer`	Yes	API key ID

Example request

curl -X DELETE \
  -H "Authorization: Bearer comvi_your_api_key" \
  https://api.comvi.io/api/v1/api-keys/2

Response

Returns 204 No Content on success.

Update API key

Update an API key’s name, description, active status, expiration, or scopes.

PUT /api/v1/api-keys/:id

Path parameters

Parameter	Type	Required	Description
`id`	`integer`	Yes	API key ID

Request body

Field	Type	Required	Description
`name`	`string`	No	Updated name
`description`	`string`	No	Updated description
`isActive`	`boolean`	No	Enable or disable the key
`expiresAt`	`string \| null`	No	Set or remove expiration
`permissions`	`string[]`	No	Updated API scopes

Example request

curl -X PUT \
  -H "Authorization: Bearer comvi_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Sync Key",
    "isActive": true,
    "permissions": ["project:read", "translations:read", "translations:write", "schema:read"]
  }' \
  https://api.comvi.io/api/v1/api-keys/1

Example response

{
  "id": 1,
  "projectId": 5,
  "name": "Production Sync Key",
  "description": "Used by GitHub Actions for pulling translations",
  "keyPrefix": "comvi_a1b2",
  "lastUsedAt": "2025-03-20T14:00:00Z",
  "expiresAt": null,
  "isActive": true,
  "permissions": ["project:read", "translations:read", "translations:write", "schema:read"],
  "createdAt": "2025-01-15T10:00:00Z",
  "updatedAt": "2025-03-25T11:00:00Z"
}

Security best practices

Use the principle of least privilege. Only grant the scopes your integration actually needs.
Set expiration dates for keys used in temporary environments (staging, feature branches).
Rotate keys periodically. Create a new key, update your integrations, then revoke the old one.
Store keys in environment variables, never in source code or config files committed to version control.
Monitor usage in the Comvi dashboard – each key logs its last usage time.

Errors

Status	Error Code	Description
`400`	`UNIQUE_CONSTRAINT`	An API key with this name already exists in the project
`400`	`INVALID_INPUT`	Invalid scopes or payload
`403`	`FORBIDDEN`	Cannot grant scopes you do not have, or insufficient access
`404`	`API_KEY_NOT_FOUND`	The specified API key does not exist

Next Steps

AuthenticationLearn about all authentication methods.

API Keys in the PlatformCreate and manage API keys from the dashboard.

CLI OverviewUse API keys with the Comvi CLI.