Mirrors/unleash.unleash
1
0
Fork 0
mirror of https://github.com/Unleash/unleash.git synced 2025-10-27 11:02:16 +01:00
Code Issues Projects Releases Wiki Activity
90296bed82
unleash.unleash/website/docs/reference/api-tokens-and-client-keys.mdx
Nuno Góis 95f4f641b5
docs: custom root roles (#4451) 
https://linear.app/unleash/issue/2-1136/custom-root-roles-documentation

- [Adds documentation referencing custom root
roles](https://unleash-docs-git-docs-custom-root-roles-unleash-team.vercel.app/reference/rbac);
- [Adds a "How to create and assign custom root roles" how-to
guide](https://unleash-docs-git-docs-custom-root-roles-unleash-team.vercel.app/how-to/how-to-create-and-assign-custom-root-roles);
 - Standardizes "global" roles to "root" roles;
- Standardizes "standard" roles to "predefined" roles to better reflect
their behavior and what is shown in our UI;
 - Updates predefined role descriptions and makes them consistent;
 - Updates the side panel description of the user form;
- Includes some boy scouting with some tiny fixes of things identified
along the way (e.g. the role form was persisting old data when closed
and re-opened);
 
 Questions:

- Is it worth expanding the "Assigning custom root roles" section in the
"How to create and assign custom root roles" guide to include the steps
for assigning a root role for each entity (user, service account,
group)?
- Should this PR include an update to the existing "How to create and
assign custom project roles" guide? We've since updated the UI;

---------

Co-authored-by: Thomas Heartman <thomas@getunleash.ai>
2023-08-10 08:21:58 +01:00

219 lines
11 KiB
Plaintext
Raw Blame History

---
title: API tokens and client keys
---
For Unleash to be of any use, it requires at least a server and a [consuming client](../reference/sdks/index.md). More advanced use cases may call for multiple clients, automated feature toggle updates, the [Unleash proxy](../generated/unleash-proxy.md) and [Unleash proxy clients](../reference/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](../how-to/how-to-create-api-tokens.mdx).
:::
Use API tokens to connect to the Unleash server API. API tokens come in four distinct types:
- [Admin tokens](#admin-tokens)
- [Personal access tokens](#personal-access-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}
Admin, client and front-end tokens contain the following pieces of information:
| Name | Description |
| --- | --- |
| Token name (sometimes called "username") | The token's name. Names are **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. |
Personal access tokens follow their own special format, and only contain an optional description for the token and an expiry date.
### API token visibility
:::info project-level visibility
Project-level visibility and access to API tokens was introduced in Unleash 4.22.
:::
By default, only admin users can create API tokens, and only admins can see their values.
However, any [client](#client-tokens client tokens) and [front-end tokens](#front-end-tokens) that are applicable to a project, will also be visible to any members of that project that have the `READ_PROJECT_API_TOKEN` permission (all project members by default).
Similarly, any project members with the `CREATE_PROJECT_API_TOKEN` permission can also create client and front-end tokens for that specific project ([how to create project API tokens](../how-to/how-to-create-project-api-tokens.mdx)).
### 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 root resources (find out more about [resources in the RBAC document](../reference/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](../reference/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.
### 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 using a personal access token to modify resources, the event log will list 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/index.md): You will _not_ be able to read toggle 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/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](../reference/sdks/index.md#server-side-sdks)
- To connect [the Unleash Proxy](../generated/unleash-proxy.md) to the Unleash API
Do **not** use client tokens in:
- [Front-end SDKs](../reference/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](../generated/unleash-proxy.md) and use [Proxy client keys](#proxy-client-keys).
### Front-end tokens
**Front-end tokens** are used with [front-end SDKs](../reference/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_)](../reference/sdks/index.md#front-end-sdks).
Do **not** use front-end tokens in:
- [Server-side SDKs](../reference/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](./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.
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 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
```
- 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/index.md#front-end-sdks) to the [Unleash Proxy](../generated/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](../generated/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](../generated/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](../reference/sdks/index.md#front-end-sdks) to the [Unleash Proxy](../generated/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.
Reference in New Issue View Git Blame Copy Permalink