Skip to main content

API Tokens and Client Keys

For Unleash to be of any use, it requires at least a server and a consuming client. More advanced use cases may call for multiple clients, automated feature flag updates, the Unleash proxy and Unleash proxy clients, and more. To facilitate communication between all these moving parts, Unleash uses a system of API tokens and client keys, all with a specific purpose in mind.

This document details the three kinds of tokens and keys that you will need to fully connect any Unleash system:

API tokens​

tip

This section describes what API tokens are. For information on how to create them, refer to the how-to guide for creating API tokens.

Use API tokens to connect to the Unleash server API. API tokens come in four distinct types:

All types use the same format but have different intended uses. Admin and client tokens are secrets and should not be exposed to end users. Front-end tokens, on the other hand, are not secret.

The parts of an API token​

Admin, client and front-end tokens contain the following pieces of information:

NameDescription
Token name (sometimes called "username")The token's name. Names are not required to be unique.
TypeWhat kind of token it is: admin, client, or front-end.
ProjectsWhat projects a token has access to.
EnvironmentWhat environment the token has access to.

Personal access tokens follow their own special format, and only contain an optional description for the token and an expiry date.

API token visibility​

Availability

Version: 4.22+

By default, only admin users can create API tokens, and only admins can see their values.

However, any [client](#client-tokens client tokens) and front-end tokens that are applicable to a project, will also be visible to any members of that project that have the READ_PROJECT_API_TOKEN permission (all project members by default).

Similarly, any project members with the CREATE_PROJECT_API_TOKEN permission can also create client and front-end tokens for that specific project (how to create project API tokens).

Admin tokens​

Admin tokens grant full read and write access to all resources in the Unleash server API. Admin tokens have access to all projects, all environments, and all root resources (find out more about resources in the RBAC document).

Use admin tokens to:

  • Automate Unleash behavior such as creating feature flags, projects, etc.

  • Write custom Unleash UIs to replace the default Unleash admin UI. Do not use admin tokens for:

  • Client SDKs: You will not be able to read flag data from multiple environments. Use client tokens instead.

Support for scoped admin tokens with more fine-grained permissions is currently in the planning stage.

Deprecation Notice We do not recommend using admin tokens anymore, they are not connected to any user, and as such is a lot harder to track.

Personal access tokens​

Personal access tokens are a special form of admin tokens and grant access to the same resources that the user that created them has access to. These permissions are dynamic, so if a user's permissions change through addition of a custom role, the token will likewise have altered permissions.

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 will stop working after the expiration date.

Use personal access tokens to:

  • Provide more fine-grained permissions for automation than an admin token provides
  • Give temporary access to an automation tool
On token expiration

It is possible to set a token's expiration date to never. However, a token that doesn't expire brings with it a few security concerns. We recommend that you use tokens with expiration dates whenever possible.

Do not use personal access tokens for:

  • Client SDKs: You will not be able to read flag data from multiple environments. Use client tokens instead.
  • Write custom Unleash UIs: Personal access tokens may expire and their permissions may change. It's better to use admin tokens tokens instead.

Client tokens​

Client tokens are intended for use in server-side client SDKs (including the Unleash Proxy) and grant the user permissions to:

  • Read feature flag information
  • Register applications with the Unleash server
  • Send usage metrics

When creating a client token, you can choose which projects it should be able to read data from. You can give it access to a specific list of projects or to all projects (including projects that don't exist yet). Prior to Unleash 4.10, a token could be valid only for a single project or all projects.

Each client token is only valid for a single environment.

Use client tokens:

Do not use client tokens in:

Front-end tokens​

Front-end tokens are used with front-end SDKs when used with the Unleash front-end API. They grant the user permission to:

  • Read the enabled flags for a given context
  • Register applications with the Unleash server
  • Send usage metrics

As with client tokens, front-end tokens can read data from one, multiple, or all existing projects.

Each front-end token is only valid for a single environment.

Use front-end tokens in:

Do not use front-end tokens in:

Format​

API tokens come in one of two formats. When we introduced environments in Unleash 4.3, we updated the format of the tokens to provide more human-readable information to the user. Both formats are still valid (you don't need to update a working token of the old format) and are described below.

Version 1​

The first version of API tokens was a 64 character long hexadecimal string. Example:

be44368985f7fb3237c584ef86f3d6bdada42ddbd63a019d26955178

Version 2​

API tokens consist of three parts:

  1. Project(s)
  2. Environment
  3. Hash

The parts are separated by two different separators: A colon (:) between the project(s) and the environment, and a full stop (.) between the environment and the hash.

The project(s) part is one of:

  • The id of a specific project, for example: default. This indicates that the token is only valid for this project.
  • A pair of opening and closing square brackets: []. This indicates that the token is valid for a discrete list of projects. The list of projects is not shown in the token.
  • An asterisk: *. This indicates that the token is valid for all projects (current and future).

The environment is the name of an environment on your Unleash server, such as development.

The hash is 64 character long hexadecimal string.

Personal access tokens do not contain project or environment information, since they mimic the user that created them. Instead, the token starts with the string user.

Some example client tokens are:

  • A token with access to flags in the "development" environment of a single project, "project-a": 
    project-a:development.be44368985f7fb3237c584ef86f3d6bdada42ddbd63a019d26955178
  • A token with access to flags in the "production" environment multiple projects: 
    []:production.be44368985f7fb3237c584ef86f3d6bdada42ddbd63a019d26955178
  • A token with access to flags in the "development" environment of all projects: 
    *:development.be44368985f7fb3237c584ef86f3d6bdada42ddbd63a019d26955178
  • A personal access token: 
    user:be7536c3a160ff15e3a92da45de531dd54bc1ae15d8455c0476f086b

Proxy client keys​

Use proxy client keys to connect Proxy client SDKs (front-end SDKs) to the Unleash Proxy. As opposed to the API tokens, Proxy client keys are not considered secret and are safe to use on any clients (refer to the the proxy documentation for more about privacy). They do not let you connect to the Unleash server API.

Proxy client keys are arbitrary strings that you must provide the Unleash proxy with on startup. They can be whatever you want 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, as mentioned in the configuration section of the Unleash proxy documentation. Connecting clients should then specify the same string as their client key.

Unleash does not generate proxy client keys for you. Because of this, they have no specific format.

Use Proxy client keys to:

Do not use Proxy client keys to:

  • Connect to the Unleash API. It will not work. Use an appropriate API token instead.