From f7081d5f3a1f618efef2817674ae9727a90cb3d0 Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Wed, 13 Apr 2022 13:45:01 +0200 Subject: [PATCH] docs: First draft of API tokens and client keys doc --- website/docs/reference/api-tokens.mdx | 94 ++++++++++++++++++++++++++- 1 file changed, 92 insertions(+), 2 deletions(-) diff --git a/website/docs/reference/api-tokens.mdx b/website/docs/reference/api-tokens.mdx index 909aabac74..042caacd65 100644 --- a/website/docs/reference/api-tokens.mdx +++ b/website/docs/reference/api-tokens.mdx @@ -1,13 +1,103 @@ --- -title: API tokens +title: API tokens and client keys --- Unleash has a number of tokens/keys that all have slightly different use cases. Here's the list of all of them: ## API tokens +Use API tokens to connect to the Unleash server API. API tokens come in two distinct types: +- [Admin tokens](#admin-tokens) +- [Client tokens](#client-tokens) + +Both types have use [the same format](#format) but have different intended uses. API tokens are considered to be *secrets* and should _not_ be exposed to end users. + ### 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](../user_guide/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](../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. + ### Client tokens -## Proxy client keys (not actual tokens!) +**Client tokens** are intended for use in [server-side client SDKs](../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). + +Each client token is only **valid for a single environment**. + +Use client tokens: +- In [server-side client SDKs](../sdks/index.md#server-side-sdks) +- To connect [the Unleash Proxy](../sdks/unleash-proxy.md) to the Unleash API + +Do _not_ use client tokens: +- In [front-end SDKs](../sdks/index.md#front-end-sdks). You will _not_ be able to connect to the Unleash server due to CORS restrictions. Use [Proxy client keys](#proxy-client-keys) instead. + +### Format + +API tokens come in one of two formats. When we introduced [environments](../user_guide/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. + +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 + ``` + +## Proxy client keys {#proxy-client-keys} + +Use proxy client keys to connect [front-end client SDKs](../sdks/index.md#front-end-sdks) to the [Unleash Proxy](../sdks/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](../sdks/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. 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](../sdks/index.md#front-end-sdks) to the [Unleash Proxy](../sdks/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.