mirror of
https://github.com/Unleash/unleash.git
synced 2025-10-27 11:02:16 +01:00
175 lines
9.3 KiB
Plaintext
175 lines
9.3 KiB
Plaintext
---
|
|
title: API Tokens and Client Keys
|
|
pagination_next: reference/front-end-api
|
|
---
|
|
|
|
## 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:
|
|
- [Client tokens](#client-tokens) for connecting [server-side client SDKs](../reference/sdks#server-side-sdks), [Unleash Edge](../reference/unleash-edge), and [Unleash Proxy](../reference/unleash-proxy) to Unleash.
|
|
- [Frontend tokens](#frontend-tokens) for connecting [client-side SDKs](../reference/sdks#client-side-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 client-side SDK to Unleash using Unleash Edge, you need both a [client](#client-tokens) and [frontend token](#frontend-tokens). See [Connect a client-side SDK to Unleash using Edge](#connect-a-client-side-sdk-to-unleash-using-edge) for an example.
|
|
|
|
## API token types
|
|
|
|
### Client tokens
|
|
|
|
Client tokens are intended for use in [server-side client SDKs](../reference/sdks#server-side-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
|
|
|
|
Client tokens are scoped to one or more projects and a single environment. When creating a client token, you can give it access to a specific list of projects or to all current or future projects. Client tokens are secrets and must not be exposed to end users.
|
|
|
|
Client tokens cannot be used in frontend SDKs; use [frontend tokens](#frontend-tokens) instead.
|
|
|
|
### Frontend tokens
|
|
|
|
Use frontend tokens for connecting [frontend SDKs](../reference/sdks#client-side-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 server-side SDKs; use [client tokens](#client-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 client SDKs, as they are not bound to an environment, they may expire, or their permissions may change. Use [client tokens](#client-tokens) instead.
|
|
|
|
### 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 three ways:
|
|
- **Admin > API access**: for client or frontend tokens; requires the Admin root role, or a custom root role with [API token permissions](#api-token-permissions).
|
|
- **Settings > API access** inside a project: for project-specific client 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 client-side SDK to Unleash using Edge
|
|
|
|
To connect a client-side SDK to Unleash using Unleash Edge, you need both a [client](#client-tokens) and [frontend token](#frontend-tokens):
|
|
- The client-side SDK needs a frontend token to communicate with Edge.
|
|
- Edge needs a client token to communicate with the Unleash server.
|
|
|
|
Ensure that the client token has at least the same project and environment scope as the frontend token.
|
|
|
|
|
|
|
|
|
|
## 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#client-side-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.
|