unleash.unleash/website/docs/reference/api-tokens-and-client-keys.mdx

---
title: API Tokens and Client Keys
pagination_next: reference/front-end-api
---

Unleash uses a system of API tokens and client keys, to facilitate communication between consuming clients such as [SDKs](../reference/sdks), [Edge](../reference/edge) or other tools and automation.

Unleash supports the following types of API tokens and keys:
- [Client tokens](#client-tokens) for connecting server-side client SDKs, Unleash Edge and Unleash Proxy to the Unleash server.
- [Frontend tokens](#frontend-tokens) for connecting client-side SDKs to Unleash using the Frontend API.
- [Personal access tokens](#personal-access-tokens) for testing and debugging or providing temporary access to an automation tool.
- [Proxy client keys](#proxy-client-keys) for connecting client-side SDKs to Unleash using Unleash Proxy.

Client tokens are secrets and must not be exposed to end users. Front-end tokens are not considered a secret.

## API token format

```
unleash-docs:development.de665dd6ea2a7d163d76a07b9c74ee880ebdc48e717d755d49759157
```

## Create an API token


## API token permissions

:::note Availability

**Version**: `4.22+`

:::

- An Admin root role - allows the user to create, view, update, or delete client or frontend tokens in any project
- A root role permission for create, view, update or delete exist for both client and frontend, such as `Create CLIENT API tokens` or `Delete FRONTEND API tokens` applies to any project
- Member: create, view, update, or delete a client or frontend token in the project they're a member of
- A custom project role with the `READ_PROJECT_API_TOKEN` permission in the project
- The Viewer role alone does not grant permissions to view API keys
- Anyone can create a personal access token for themselves

### Admin tokens

:::warning

Admin tokens are deprecated. Use other tokens types:
- With [Open Source](https://www.getunleash.io/pricing) and [Pro](../availability#plans), use [personal access tokens](#personal-access-tokens).
- With [Enterprise](https://www.getunleash.io/pricing), use [service accounts](./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](../reference/rbac#core-principles).


### 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

:::info 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](../reference/sdks): You will _not_ be able to read flag data from multiple environments. Use [client tokens](#client-tokens) instead.
-   Write custom Unleash UIs: Personal access tokens may expire and their permissions may change. It's better to use [admin tokens](#admin-tokens) tokens instead.

### Client tokens

**Client tokens** are intended for use in [server-side client SDKs](../reference/sdks#server-side-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:

-   In [server-side client SDKs](../reference/sdks#server-side-sdks)
-   To connect [the Unleash Proxy](../reference/unleash-proxy) to the Unleash API

Do **not** use client tokens in:

-   [Front-end SDKs](../reference/sdks#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) and create a [front-end token](#front-end-tokens).
-   Configure an [Unleash Proxy](../reference/unleash-proxy) and use [Proxy client keys](#proxy-client-keys).

### Front-end tokens

**Front-end tokens** are used with [front-end SDKs](../reference/sdks#front-end-sdks) when used with the [Unleash front-end API](./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](#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_)](../reference/sdks#front-end-sdks).

Do **not** use front-end tokens in:

-   [Server-side SDKs](../reference/sdks#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](./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 {#proxy-client-keys}

Use proxy client keys to connect [Proxy client SDKs (front-end SDKs)](../reference/sdks#front-end-sdks) to the [Unleash Proxy](../reference/unleash-proxy). 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](../reference/unleash-proxy#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](../reference/unleash-proxy#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](../reference/sdks#front-end-sdks) to the [Unleash Proxy](../reference/unleash-proxy)
-   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.