Skip to content

Latest commit

 

History

History
103 lines (69 loc) · 5.11 KB

api-tokens-and-client-keys.mdx

File metadata and controls

103 lines (69 loc) · 5.11 KB
Raw
title
API tokens and client keys

Unleash has a number of tokens/keys that all have slightly different use cases. Here's the list of all of them:

API tokens

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

Both types have use the same format but have different intended uses. API tokens are considered to be secrets and should not be exposed to end users.

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 global resources (find out more about resources in the RBAC document).

Use admin tokens to:

  • automate Unleash behavior such as creating feature toggles, projects, etc.
  • write custom Unleash UIs to replace the default Unleash admin UI

Do not use admin tokens for:

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

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 toggle 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).

Each client token is only valid for a single environment.

Use client tokens:

Do not use client 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.

Some example client tokens are:

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

Proxy client keys {#proxy-client-keys}

Use proxy client keys to connect front-end client 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. 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.