Managing Operator Tokens

Operator tokens are labeled API credentials (opt_...) that authenticate requests to the Translation API and the MCP endpoint. Each token belongs to your account, acts on your behalf, and is scoped to the workspaces you choose.

Creating an Operator Token

1. Navigate to Account → Operator tokens (/account/settings/tokens)
2. Click Create operator token
3. Enter an operator label (e.g., "Claude", "n8n pipeline", "CI")
4. Choose a workspace scope:
   • All workspaces I own — works in every workspace where you are the owner
   • Specific workspaces — any workspaces you are currently a member of
5. Optionally narrow the token to specific projects (by slug)
6. Pick an expiration (1 day to 1 year, or never)
7. Copy your token immediately — it is only shown once

Using Your Operator Token

Include your token in the Authorization header of every request:

curl https://your-domain.com/api/v1/translate \
  -H "Authorization: Bearer opt_your-token" \
  -H "Content-Type: application/json" \
  -d '{"text":"Hello","target_lang":"es","workspace":"my-workspace"}'

Pass workspace (slug or id) whenever the token can access more than one workspace. If it can only access one, the workspace is inferred. Projects can be addressed with project_slug.

Scope and Permissions

Operator tokens resolve to your live memberships at request time:

• All workspaces I own tracks only workspaces where you currently have the owner role
• Specific workspaces is re-checked against your current memberships, so losing membership immediately revokes access
• Translation (write) requires the owner or admin role in the target workspace
• Usage (read) is allowed for any workspace member
• All tokens in a workspace share the same usage quota

If you are removed from a workspace or demoted to member, the token loses write access there automatically.

Project Narrowing

When you select specific projects, every request must name one of them via project_slug. Requests without a project are rejected. If a project slug exists in more than one of your scoped workspaces, pass workspace to disambiguate.

Security Best Practices

Do

• Store tokens in environment variables
• Use different tokens for development and production
• Scope tokens to the minimum workspaces and projects needed
• Set expirations for temporary integrations
• Revoke unused tokens immediately

Don't

• Commit tokens to source control
• Share tokens in plain text
• Use the same token for multiple environments
• Expose tokens in client-side code

Environment Variables

Store your token securely:

# .env.local (never commit this file)
TRANSLATE_API_KEY=opt_your-token

// Use in your application
const apiKey = process.env.TRANSLATE_API_KEY;

Revoking a Token

If a token is compromised or no longer needed:

1. Go to Account → Operator tokens
2. Find the token you want to revoke
3. Click Revoke
4. Confirm

Workspace Visibility

Workspace owners and admins can see every operator token that can currently reach their workspace under Workspace Settings → Operators. That list is read-only; only the token owner can revoke their own token.

Token Limits by Plan