API keys

Choose personal or service authority, store the secret once, and replace credentials without losing track of their callers.

An API key lets a caller act with a defined authority. A personal key follows a person's membership and permissions. An organization service key belongs to the organization, so automation can remain independent of one colleague's departure. With RBAC, a service key can also have its own role and resource scope.

The secret is shown at creation and cannot be recovered from later key records. Store it immediately in a secret manager or the caller's supported credential store. Keep it out of source files, committed configuration, screenshots, and support messages.

Use a personal key for work done as a person #

In the selected organization's Settings → API keys → Personal, create and name a personal key. A member can create one for their own use. Its authority follows that creator's current membership and effective permissions; it cannot receive a separate role or per-localization-engine scope as a service key can.

This is useful for a local caller acting as its operator. If the member leaves or loses authority, the key's access changes too. Use a service key when organizational automation should not depend on that person's continuing access.

Create a service key #

In the selected organization's Settings → API keys → Organization, select New organization key. Service keys are available on every plan. Creating one requires org:manage_api_keys.

Without RBAC, a service key cannot be narrowed: it reads and translates with every localization engine in the organization. The creation form shows a note instead of role and engine fields.

This basic access does not allow the key to edit or delete localization engines, review translations, or administer the organization.

With RBAC, you can give the key a role, localization-engine scope, or both, and edit them later. The caller must be able to delegate the selected role and translate with every scoped localization engine. Read permission alone is insufficient to grant translation scope.

The service-role whitelist is engine:read and engine:translate. A role must belong to the organization and cannot contain broader administrative permissions. A service key can also have no role and rely on deliberate resource grants.

Configure localization-engine and content-resource scope separately, then read back each saved field. One authority update can fail while another succeeds. Role permissions and explicit grants combine additively; a narrow scope does not cancel broader role-derived access. With RBAC, creation alone does not grant useful translation authority to a key with neither an appropriate role nor resource grants.

Use the key-management interface for creation and scope edits. When automating this lifecycle, check that the chosen client exposes the required management operation rather than assuming all clients do.

Before removing RBAC

If RBAC is removed, ordinary service keys fall back to organization-wide read-and-translate access. Stored role and engine restrictions no longer limit that access. Revoke or rotate keys before removing RBAC if those restrictions are required. Purpose-specific credentials such as SCIM keys have separate access requirements.

Rotate or revoke a credential #

Rotation is a manual replacement:

  1. Create a replacement with the intended key type and least necessary authority.
  2. Store its secret in the caller's secret-management mechanism.
  3. Update dependent callers and verify a small intended operation through their supported interface.
  4. Revoke the old key after verification. If exposure requires immediate containment, revoke first and account for the interruption.
  5. Inspect current key records and caller failures for missed dependencies.

An organization member with access to the key record can revoke an ordinary personal or service key. This gate is broader than service-key creation or scope editing. SCIM key revocation requires the organization Owner. Refer to the key's identifier, not its secret, when discussing removal.

Revocation does not erase copies held elsewhere or revoke browser sessions. No automatic rotation or expiration schedule is implied by this lifecycle.

Configure the actual caller #

REST requests use the selected API's X-API-Key header. A 401 points to authentication; a 403 points to refused authority. Confirm the credential for the former and the principal's permissions and resource scope for the latter. Keep credentials out of improvised URLs.

Use API authentication, CLI authentication, or the MCP connection contract for the caller's wire and storage behavior. The selected localization engine must remain within that caller's authority.