---
title: API tokens and client keys
pagination_next: reference/front-end-api
---

import SearchPriority from '@site/src/components/SearchPriority';

<SearchPriority level="high" />

## Overview

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

Unleash supports the following types of API tokens:
- [Backend tokens](#backend-tokens) for connecting [backend SDKs](../reference/sdks#backend-sdks), [Unleash Edge](../reference/unleash-edge), and [Unleash Proxy](../reference/unleash-proxy) to Unleash.
- [Frontend tokens](#frontend-tokens) for connecting [frontend SDKs](../reference/sdks#frontend-sdks) to Unleash using the [Frontend API](../reference/front-end-api) or [Unleash Edge](../reference/unleash-edge).
- [Personal access tokens](#personal-access-tokens) for testing and debugging or providing temporary access to an automation tool.
- [Service account tokens](/reference/service-accounts) for providing API access to integrations or automation tools.

To connect a frontend SDK to Unleash using Unleash Edge, you need both a [backend](#backend-tokens) and [frontend token](#frontend-tokens). See [Connect a frontend SDK to Unleash using Edge](#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](../reference/sdks#backend-sdks), [Unleash Edge](../reference/unleash-edge), and [Unleash Proxy](../reference/unleash-proxy) 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](#frontend-tokens) instead.

### Frontend tokens

Use frontend tokens for connecting [frontend SDKs](../reference/sdks#frontend-sdks) to Unleash using the [Unleash Frontend API](./front-end-api) or [Unleash Edge](../reference/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.

Frontend tokens cannot be used in backend SDKs; use [backend tokens](#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](/reference/service-accounts).

### Admin tokens

:::warning

Admin tokens are deprecated. Use other token 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).


## API token permissions

:::note Availability

**Version**: `4.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.                          | 

## API token format

API tokens consist of three parts:

1. Project information
2. Environment
3. Hash

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

```
{{projects}}:{{environment}}.{{hash}}
```

The project value of the token can be one of:
-   A single project ID, for example, `default`: when the token can only access a single project.
-   `[]`: when the token is valid for a specific set of projects. The list of projects is not shown in the token.
-   `*`: when the token is valid for all current and future projects.

The environment value of the token is the name of an environment on your Unleash instance, such as `development`. The hash is a 64-character-long hexadecimal string.

Personal access tokens start with the string `user`, and do not contain additional project or environment information.

Some example API tokens are:

-   A token with access to the `development` environment of a single project, `new-checkout-flow`:
    ```
    new-checkout-flow:development.be44368985f7fb3237c584ef86f3d6bdada42ddbd63a019d26955178
    ```
-   A token with access to the `production` environment in multiple projects:
    ```
    []:production.be44368985f7fb3237c584ef86f3d6bdada42ddbd63a019d26955178
    ```
-   A token with access to the `development` environment in all current and future projects:
    ```
    *:development.be44368985f7fb3237c584ef86f3d6bdada42ddbd63a019d26955178
    ```
-   A personal access token:
    ```
    user:be7536c3a160ff15e3a92da45de531dd54bc1ae15d8455c0476f086b
    ```


Note, in Unleash v4.3 or less, API tokens are a 64-character-long hexadecimal string with no additional information. For example:

```
be44368985f7fb3237c584ef86f3d6bdada42ddbd63a019d26955178
```

## Create an API token

Depending on your [permissions](#api-token-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](#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](#api-token-permissions).
- **Profile > View profile settings > Personal API tokens**: for [personal access tokens](#personal-access-tokens).

## Connect a frontend SDK to Unleash using Edge

To connect a frontend SDK to Unleash using Unleash Edge, you need both a [backend](#backend-tokens) and [frontend token](#frontend-tokens):
    - 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](/img/sdk-token-example.jpg)


## Proxy client keys

:::warning

Unleash Proxy is in maintenance mode. Use [Unleash Edge](../reference/unleash-edge) instead.

:::

You can use proxy client keys to connect [frontend SDKs](../reference/sdks#frontend-sdks) to [Unleash Proxy](../reference/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.

:::info Creating proxy client keys

To designate a string as a proxy client key, add it to the `clientKeys` list when [starting the proxy](../reference/unleash-proxy#configuration-options). 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.
