API tokens and client keys | Unleash Documentation

Unleash uses API tokens to authenticate consuming clients such as SDKs, Unleash Edge, and other tools and automation.

Unleash supports the following types of API tokens:

Backend tokens for connecting backend SDKs or Unleash Edge to Unleash.
Frontend tokens for connecting frontend SDKs to Unleash using the Frontend API or Unleash Edge.
Personal access tokens for testing and debugging or providing temporary access to an automation tool.
Service account tokens for providing API access to integrations or automation tools.

Each token is either a secure token or a legacy token. See Token versions for the differences.

To connect a frontend SDK to Unleash using Unleash Edge, you need both a backend and frontend token. See Connect a frontend SDK to Unleash using Edge for an example.

API token types

Backend tokens

Backend tokens are intended for use in backend SDKs or Unleash Edge to grant the permissions to:

Reading feature flag information
Registering applications with the Unleash server
Sending usage metrics

Backend tokens are scoped to one or more projects and a single environment. When creating a backend token, you can give it access to a specific list of projects or to all current or future projects. Backend tokens are secrets and must not be exposed to end users.

Backend tokens cannot be used in frontend SDKs; use frontend tokens instead.

Frontend tokens

Use frontend tokens for connecting frontend SDKs to Unleash using the Unleash Frontend API or Unleash Edge. They grant the user permission to:

Reading enabled flags for a given context
Registering applications with the Unleash server
Sending usage metrics

Frontend tokens are scoped to one or more projects and a single environment. When creating a frontend token, you can give it access to a specific list of projects or to all current or future projects. Frontend tokens are not considered secret and are safe to expose client-side, including secure tokens.

Frontend tokens cannot be used in backend SDKs; use backend tokens instead.

Personal access tokens

Personal access tokens reflect the permissions of the user who creates them. If the user’s permissions change, such as through the addition of a custom role, the token automatically updates to match the new permissions. You can use personal access tokens for testing, debugging, or giving temporary access to automation tools.

When you use a personal access token to modify resources, the events record the token creator’s name for that operation.

Personal access tokens with a lifetime expire and stop working after their expiration date. Although you can set the token to not expire, we recommend using tokens with expiration dates to follow security best practices.

Personal access tokens are not suitable for use in SDKs, as they are not bound to an environment, they may expire, or their permissions may change.

Service account tokens

Service account tokens provide API access to integration and automation tools. To learn more, go to Service Accounts.

Admin tokens

Admin tokens are deprecated. Use other token types:

With Open Source; use personal access tokens.
With Enterprise; use service accounts.

Admin tokens grant full read and write access to all resources in the Unleash server API. This includes all projects, all environments, and all root resources.

Token versions

Each API token is either a secure token or a legacy token. The version determines what the token looks like, how Unleash stores it, and when you can view the complete token, meaning the full value you use to authenticate.

	Secure token	Legacy token
Unleash version	Created in v8.3 or later	Created in v8.2 or earlier
Token secret	Contains `v2_`	Doesn’t contain `v2_`
Stored in the Unleash database	A selector and a verifier. Unleash never stores the complete token.	The complete token
Complete token shown	Only once, when you create it	When you create it, and from the get API tokens endpoint
`secure` field in API responses	`true`	`false`

Unleash Cloud always runs the latest version, so every token you create there is a secure token. If you self-host, your Unleash version determines which version of token you create.

Unleash shows a secure token only once, when you create it. Copy the token immediately and store it in a secrets manager.

Legacy tokens keep working after you upgrade. To replace them, see How Unleash stores tokens > Legacy tokens > Upgrade to secure tokens.

How Unleash stores tokens

How Unleash stores a token depends on its version:

Secure tokens

Legacy tokens

For a secure token, Unleash stores two values instead of the complete token:

A selector, which identifies the token’s database record. The selector is part of the token, so Unleash can find the correct record during authentication. The selector isn’t a secret.
A verifier, which Unleash derives from the complete token and uses to verify it. Unleash stores the verifier in the database and never includes it in the token or in API responses.

When Unleash receives a secure token, it extracts the selector, retrieves the matching verifier, and verifies the token. Unleash can’t reconstruct the complete token from these values, and the values alone can’t authenticate a request. This limits the impact if someone gains read access to your database or its backups.

Because Unleash never stores the complete token:

You can’t retrieve a secure token after creation. If you lose one, rotate it.
The get API tokens endpoint returns the selector in the secret field and sets secure: true.
The update API token and delete API token endpoints accept either the selector or the complete token as the token identifier.
Events for secure token operations include the selector and tokenVersion: 2, never the complete token.

Secure storage applies to the Unleash database only. Other systems that hold your tokens store the complete token, including Terraform state and Unleash Edge when you configure persistent storage with Redis, S3, or a backup folder. Protect that storage and its backups as you would any other secret. For Edge, see production deployment.

API token format

Backend, frontend, and deprecated admin tokens consist of three parts:

Project information
Environment
Secret

The parts are separated by two delimiters: a colon (:) between the projects and the environment, and a period (.) between the environment and the secret.

The project value can be one of:

A single project ID, for example, default: the token can only access that project.
[]: the token is valid for a specific set of projects. The project IDs are not shown in the token.
*: the token is valid for all current and future projects.

The environment value is the name of an environment on your Unleash instance, such as development. Admin tokens use *:* as the project and environment value.

Personal access tokens and service account tokens start with user:, followed by the secret. They do not contain project or environment information.

The format of the secret depends on whether the token is a secure token or a legacy token:

Secure tokens

Legacy tokens

The secret of a secure token starts with v2_, followed by the selector and a random string, both Base64 URL-encoded. Treat the complete token, including its selector, as a secret.

{{projects}}:{{environment}}.v2_{{selector}}_{{random}}

Personal access tokens and service account tokens use the same secret:

user:v2_{{selector}}_{{random}}

Some example API tokens are:

A token with access to the development environment of a single project, new-checkout-flow:

new-checkout-flow:development.v2_Y8mfumDNYCBPIzU_X48tyA_P3XdoA9Fel9KoioeVKw5FWmA-PGd2jxq9SYj2hqCwlk

A token with access to the production environment in multiple projects:

[]:production.v2_jgjspSh-Z8ArlCHA91NDZQ_7o96eJAm7t1uJQFmT_Jzav5_MQv8yKjEpFmlsSYuP_M

A token with access to the development environment in all current and future projects:
```
*:development.v2_6mV-cGeq4amfxekzzk6nOA_H6QEoJKSQaqa66MxSyAz2lBvg1OlFxnTdHYAWOwIhHI
```

A personal access token or service account token:

user:v2_nn1XkimQkV8SSoUPEeuE3Q_48zN1UZIx-IPXr3vMB-8DS1zC-6LoZHtn0ara9dLTP4

API token permissions

v4.22

The following table provides a summary of what actions different roles can perform with API tokens:

Role/Permission	Details
Admin root role	Can view, create, update, or delete tokens for any project.
Custom root role with API token permission	Can view, create, update, or delete tokens for any project with the corresponding permission, such as `CREATE_CLIENT_API_TOKEN`.
Member project role	Can view, create, update, or delete tokens within the project.
Custom project role with API token permission	Can view, create, update, or delete tokens within the project with the corresponding permission, `CREATE_PROJECT_API_TOKEN`.
Viewer root role	Cannot view, create, update, or delete tokens.
Any role	Can create personal access tokens.

Create an API token

Depending on your permissions, you can create API tokens in the Unleash Admin UI in four ways:

Admin settings > Access control > API access: for backend or frontend tokens; requires the Admin root role, or a custom root role with API token permissions.
Admin settings > Service accounts > New service account: for creating a service account and assigning a token.
Settings > API access inside a project: for project-specific backend or frontend tokens; permitted for project Members or users with a corresponding root role.
Profile > View profile settings > Personal API tokens: for personal access tokens.

Unleash shows the complete token once, right after you create it. Copy it before you close the confirmation. Token lists show a token’s name, type, and scope only.

To create tokens programmatically, use the create API token, create project API token, create personal access token, or create service account token endpoint. For secure tokens, the create response is the only response that includes the complete token in the secret field.

Token expiry and rotation

Requests with an expired token are rejected, so rotate tokens before they expire. How you set a token’s expiration date depends on the token type:

Token type	Admin UI	Admin API
Backend and frontend tokens	By default, tokens are created without an expiration.	Set the optional `expiresAt` property with the create API token or create project API token endpoint, or add an expiration date to an existing token with the update API token endpoint.
Personal access tokens	Choose an expiration when creating the token: 7, 30, or 60 days, a custom date, or never.	Set the required `expiresAt` property with the create personal access token endpoint.
Service account tokens	Choose an expiration when creating the token: 7, 30, or 60 days, a custom date, or never.	Set the required `expiresAt` property with the create service account token endpoint.

For backend and frontend tokens, we recommend rotating tokens on a regular schedule rather than setting an expiration date. This keeps token hygiene in your control without the risk of a token expiring unnoticed.

A token’s access configuration, that is its type, projects, and environment, cannot be changed after creation. Unleash does not rotate tokens automatically.

Rotate a token

To rotate a token:

Create a new token with the same type, project, and environment scope, and copy it.
Update your SDKs and integrations to use the new token.
Delete the old token once nothing is using it.

If you rotate a token in Unleash Cloud or in a self-hosted instance running v8.3 or later, the new token is a secure token. When you delete a legacy token, Unleash removes the complete token from the database. Copies in existing database backups remain until your retention policy removes them, so keep protecting those backups.

Expiration notifications

Beta v8.1

Unleash notifies you before a service account token or personal access token expires. The token’s creator receives an email ahead of the expiration date, giving you time to rotate the token before your automations and integrations lose access.

Connect a frontend SDK to Unleash using Edge

To connect a frontend SDK to Unleash using Unleash Edge, you need both a backend and frontend token:

The frontend SDK needs a frontend token to communicate with Edge.
Edge needs a backend token to communicate with the Unleash server.

Ensure that the backend token has at least the same project and environment scope as the frontend token.

Diagram showing the types of tokens needed to connect a frontend SDK with Edge, and Edge with Unleash

Proxy client keys

Unleash Proxy is in maintenance mode. Use Unleash Edge instead.

You can use proxy client keys to connect frontend SDKs to Unleash Proxy. Proxy client keys are not considered a secret and are safe to expose client-side.

Proxy client keys are arbitrary strings that you provide the Unleash proxy with on startup. They can be any string you choose, and you create them yourself.

Creating proxy client keys

To designate a string as a proxy client key, add it to the clientKeys list when starting the proxy. Connecting clients should then specify the same string as their client key.

Proxy client keys cannot be used to connect to the Unleash API; use API tokens instead.