mirror of
https://github.com/Unleash/unleash.git
synced 2025-01-31 00:16:47 +01:00
155 lines
7.4 KiB
Plaintext
155 lines
7.4 KiB
Plaintext
---
|
|
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.
|
|
|
|
## API token types
|
|
|
|
### Client tokens
|
|
|
|
Client tokens are intended for use in [server-side client SDKs](../reference/sdks#server-side-sdks) 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#front-end-sdks) using the [Unleash Frontend API](./front-end-api). 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 for security purposes.
|
|
|
|
Personal access tokens are not suitable for Client SDKs, as they cannot read flag data from multiple environments, they may expire, or their permissions may change. Use [Client tokens](#client-tokens) instead.
|
|
|
|
### 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).
|
|
|
|
|
|
## API token permissions
|
|
|
|
:::note Availability
|
|
|
|
**Version**: `4.22+`
|
|
|
|
:::
|
|
|
|
### Client and Frontend tokens
|
|
|
|
The following table provides a summary of what roles and permissions allow a user to view, create, update, or delete Client and Frontend tokens in Unleash:
|
|
|
|
| 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. |
|
|
| **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. |
|
|
| **Viewer Root Role** | Cannot view, create, update, or delete tokens. |
|
|
|
|
### Personal access tokens
|
|
|
|
Any user can create personal access tokens that mirror the permissions they have.
|
|
|
|
## API token format
|
|
|
|
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.
|
|
|
|
```
|
|
{{projects}}:{{environment}}.{{hash}}
|
|
```
|
|
|
|
The **project(s)** part is one of:
|
|
|
|
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 projects (current and future)**.
|
|
|
|
The environment is the name of an environment on your Unleash instance, such as `development`. The hash is 64 character long hexadecimal string.
|
|
|
|
Personal access tokens start with the string `user`, and do not contain additional project or environment information.
|
|
|
|
Some example client 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
|
|
|
|
.. some detailed steps here
|
|
|
|
## Proxy client keys
|
|
|
|
Use proxy client keys to connect [Frontend SDKs](../reference/sdks#front-end-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). Connecting clients should then specify the same string as their client key.
|
|
|
|
:::
|
|
|
|
|
|
Proxy clients keys cannot be used to connect to the Unleash API, use [API tokens](#api-tokens) instead.
|