Personal Access Tokens

Personal Access Tokens (PATs) let you authenticate with the Locize API using a single token that works across all projects you have access to. They are primarily designed for the MCP server integration, but can also be used for multi-tenant workflows or other scenarios requiring cross-project access. While API keys remain recommended for direct API usage, PATs provide a convenient alternative when a single credential across projects is needed.

Recommendation: For standard API usage, we still recommend using API keys. They are project-scoped, easier to manage per project, and the preferred choice for most integrations. PATs are best suited for MCP and scenarios where cross-project access from a single credential is possible in an easier way.

PAT vs API Key

Locize offers two types of credentials for API access:

	API Key	Personal Access Token
Scope	Single project	All projects you can access
Created in	Project settings	My Profile
Permissions	Role-based (admin/user/readonly) with version/language/namespace restrictions	Coarse scopes (read/write/manage/admin) combined with your project role
Best for	Client-side SDKs, single-project scripts, direct API usage (recommended)	MCP integration, multi-tenant workflows, cross-project automation
Plan limits	Number of keys limited by plan tier	Bound to user (not to project)

When to use which:

Use an API key (recommended) for direct API usage, single-project integrations, and client-side SDKs (e.g. i18next, locizify).

Use a PAT for MCP server integration, multi-tenant structures where you need to manage multiple tenants with a single credential, or other scenarios requiring cross-project access.

Creating a Personal Access Token

Go to My Profile in the Locize app.
In the Personal access tokens card, click Generate token.
Enter a descriptive name (e.g. "CI pipeline", "MCP access").
Select the scopes your token needs (see below).
Optionally set an expiry date.
Click Create.

Important: The token value is shown only once after creation. Copy it immediately and store it securely. You will not be able to see the full token again.

Scopes

Each scope grants access to a category of API operations. Scopes are additive — select only what your integration needs.

Scope	Allows	Example operations
read	Fetching data	Download translations, list namespaces/languages/versions/branches, view project stats
write	Modifying translations	Update/create translations, report missing keys, manage namespaces
manage	Project structure changes	Publish versions, create/merge/delete branches, copy versions, manage languages
admin	Administrative operations	User management, project settings, billing, invitations

Note: PAT scopes act as an additional gate on top of your project role. A PAT with write scope cannot modify translations in a project where your role is readonly, even though the scope would technically allow it. Both the scope and your project role must permit the action.

Using a PAT

Pass the token in the Authorization header, exactly like an API key. Public namespace downloads don't require authentication, but write operations and private downloads do:

# Fetching translations (no auth required for public namespaces)
curl https://api.locize.app/{projectId}/{version}/{language}/{namespace}

# Write operation (auth required — PAT needs "write" scope)
curl -X POST \
  -H "Authorization: Bearer lz_pat_..." \
  -H "Content-Type: application/json" \
  -d '{"new.key": "New value"}' \
  https://api.locize.app/missing/{projectId}/{version}/{language}/{namespace}

The server detects the token type automatically by its lz_pat_ prefix. No other configuration changes are needed — PATs work with all existing API endpoints.

IP and Origin Restrictions

For additional security, you can restrict (like API Keys) where your PAT can be used from:

IP restrictions: Limit API calls to specific IP addresses or CIDR ranges (e.g. your CI server's IP).
Origin restrictions: Limit requests to specific HTTP origins.

To configure restrictions, edit your token in My Profile > Personal access tokens.

Expiry

You can set an optional expiry date when creating a PAT. After expiry, the token stops working immediately.

Tokens without an expiry date remain valid until manually revoked.
For automated workflows, consider setting an expiry and rotating tokens periodically.

Revoking a Token

To revoke a PAT:

Go to My Profile > Personal access tokens.
Click the delete/revoke button on the token you want to remove.
Confirm the action.

Revocation is immediate. Any integration using the revoked token will receive authentication errors.

Security Best Practices

Treat PATs like passwords. Never commit them to version control or expose them in client-side code.
Use minimal scopes. Only grant the scopes your integration actually needs. Most read-only integrations only need read.
Set expiry dates. Especially for tokens used in CI/CD — rotate them regularly.
Use IP restrictions when possible to limit token usage to known infrastructure.
Rotate tokens if you suspect a leak. Revoke the old token and create a new one immediately.
Use environment variables or secret management (e.g. GitHub Secrets, Vault) to store tokens in automated pipelines.