Mirrors/unleash.unleash
1
0
Fork 0
mirror of https://github.com/Unleash/unleash.git synced 2024-12-28 00:06:53 +01:00
Code Issues Projects Releases Wiki Activity
9e1241d728
unleash.unleash/website/docs/reference/api-tokens-and-client-keys.mdx
andreas-unleash be4de289a1
fix: project api token docs (#3485) 
<!-- Thanks for creating a PR! To make it easier for reviewers and
everyone else to understand what your changes relate to, please add some
relevant content to the headings below. Feel free to ignore or delete
sections that you don't think are relevant. Thank you! ❤️ -->
[Previous PR (has the
comments)](https://github.com/Unleash/unleash/pull/3405)

## About the changes
<!-- Describe the changes introduced. What are they and why are they
being introduced? Feel free to also add screenshots or steps to view the
changes if they're visual. -->

<!-- Does it close an issue? Multiple? -->
Closes #

<!-- (For internal contributors): Does it relate to an issue on public
roadmap? -->
<!--
Relates to [roadmap](https://github.com/orgs/Unleash/projects/10) item:
#
-->

### Important files
<!-- PRs can contain a lot of changes, but not all changes are equally
important. Where should a reviewer start looking to get an overview of
the changes? Are any files particularly important? -->


## Discussion points
<!-- Anything about the PR you'd like to discuss before it gets merged?
Got any questions or doubts? -->

---------

Signed-off-by: andreas-unleash <andreas@getunleash.ai>
Co-authored-by: Thomas Heartman <thomas@getunleash.ai>
2023-04-13 11:08:54 +03: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 global 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