--- title: API tokens and client keys --- For Unleash to be of any use, it requires at least a server and a [consuming client](../sdks/index.md). More advanced use cases may call for multiple clients, automated feature toggle updates, the [Unleash proxy](../sdks/unleash-proxy.md) and [Unleash proxy clients](../sdks/index.md#front-end-sdks), 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: - [Admin tokens](#admin-tokens) for updating resources in Unleash - [Client tokens](#client-tokens) for connecting server-side client SDKs and the Unleash proxy to the Unleash server - [Proxy client keys](#proxy-client-keys) for connecting proxy client SDKs to the Unleash proxy. ## 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](../user_guide/token.mdx). ::: Use API tokens to connect to the Unleash server API. API tokens come in three distinct types: - [Admin tokens](#admin-tokens) - [Client tokens](#client-tokens) - [Front-end tokens](#front-end-tokens) All types use [the same format](#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 {#token-data} An API token contains the following pieces of information: | Name | Description | | --- | --- | | Token name (sometimes called "username") | The token's name. Names or **not** required to be unique. | | Type | What kind of token it is: admin, client, or front-end. | | Projects | What projects a token has access to. | | Environment | What environment the token has access to. | ### 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](../user_guide/rbac.md#core-principles)). 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: - [Client SDKs](../sdks/index.md): You will _not_ be able to read toggle data from multiple environments. Use [client tokens](#client-tokens) instead. 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](../sdks/index.md#server-side-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). 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: - In [server-side client SDKs](../sdks/index.md#server-side-sdks) - To connect [the Unleash Proxy](../sdks/unleash-proxy.md) to the Unleash API Do **not** use client tokens in: - [Front-end SDKs](../sdks/index.md#front-end-sdks). You will _not_ be able to connect to the Unleash server due to CORS restrictions. To connect front-end SDKs, choose one of the following options: - Enable the [Unleash front-end API](./front-end-api.md) and create a [front-end token](#front-end-tokens). - Configure an [Unleash Proxy](../sdks/unleash-proxy.md) and use [Proxy client keys](#proxy-client-keys). ### Front-end tokens **Front-end tokens** are used with [front-end SDKs](../sdks/index.md#front-end-sdks) when used with the [Unleash front-end API](./front-end-api.md). They grant the user permission to: - Read the enabled toggled for a given context - Register applications with the Unleash server - Send usage metrics As with [client tokens](#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: - [Front-end SDKs (also known as _proxy clients_)](../sdks/index.md#front-end-sdks). Do **not** use front-end tokens in: - [Server-side SDKs](../sdks/index.md#server-side-sdks). The format is different, so they won't work correctly. ### Format API tokens come in one of two formats. When we introduced [environments](../user_guide/environments.md) 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 [Proxy client SDKs (front-end SDKs)](../sdks/index.md#front-end-sdks) to the [Unleash Proxy](../sdks/unleash-proxy.md). As opposed to the [API tokens](#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](../sdks/unleash-proxy.md#we-care-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**. :::info 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](../sdks/unleash-proxy.md#configuration). 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: - Connect [Proxy client SDKs](../sdks/index.md#front-end-sdks) to the [Unleash Proxy](../sdks/unleash-proxy.md) - Connect your own custom Proxy clients (or pure HTTP requests) to the Unleash Proxy Do **not** use Proxy client keys to: - Connect to the Unleash API. It will not work. Use an appropriate [API token](#api-tokens) instead.