Mirrors/unleash.unleash
1
0
Fork 0
mirror of https://github.com/Unleash/unleash.git synced 2024-12-22 19:07:54 +01:00
Code Issues Projects Releases Wiki Activity
efd9e523ed
unleash.unleash/website/docs/reference/api-tokens-and-client-keys.mdx
Thomas Heartman 415e1b0596
Source proxy and Edge docs from GitHub (#3122) 
## What

The main purpose of this PR is to

1. Delete the proxy docs in this repo and replace them with the proxy's
GitHub readme.
2. Add the docs for Unleash Edge.

### Detailed change description

This PR contains a lot of small changes in a large number of files. To
make it easier to get an overview, here's a detailed description of what
happens where:

#### In the `website/docs`directory

Except for the deletion of the proxy doc, all changes in this directory
are rewriting internal links, so that they point to the newly generated
document instead.

#### `package.json` and `yarn.lock`

When including the documentation for Edge, we also want to render the
mermaid diagrams it uses. Docusaurus supports this via a plugin. All
changes in these files are related to installing that plugin.

#### `docusaurus.config.js`

There's two types of changes in this file:

1. Mermaid-related changes: we ask docusaurus to render mermaid in
markdown files and add the plugin

2. Document generation. There's some rewrites to the sdk doc generation
plus an entirely new section that generates docs for Edge and the proxy

#### `sidebars.js`

Two things:

1. Add the edge docs
2. Move both the Edge and the proxy docs up a level, so that they're
directly under "reference docs" instead of nested inside "unleash
concepts".

#### In the `website/remote-content` directory

These are the remote content files. Previously, all of this lived only
in a `readme-fns.js` file, but with the introduction of Edge and proxy
docs, this has been moved into its own directory and refactored into
three files (`shared`, `sdks`, `edge-proxy`).

#### `custom.css`

Style updates to center mermaid diagrams and provide more space around
them.

#### In `static/img`

The image files that were included in the proxy doc and that have been
deleted.

## Why

For two reasons:

1. Reduce duplication for the proxy. Have one source of truth.
2. Add docs for edge.

## Discussion points and review wishes

This is a big PR, and I don't expect anyone to do a line-by-line review
of it, nor do I think that is particularly useful. Instead, I'd like to
ask reviewers to:

1. Visit the [documentation
preview](https://unleash-docs-git-docs-source-proxy-gh-unleash-team.vercel.app/reference/unleash-proxy)
and have a look at both the proxy docs and the Edge docs. Potentially
have a look at the SDK docs too to verify that everything still works.

2. Consider whether they think moving the proxy and edge docs up a level
(in the sidebar) makes sense.

3. Let me know what slug they'd prefer for the Edge docs. I've gone with
`unleash-edge` for now (so that it's
`docs.getunleash.io/reference/unleash-edge`), but we could potentially
also just use `edge`. WDYT?

4. Read through the detailed changes section.

5. Let me know if they have any other concerns or questions.

## Screenies

The new proxy doc:


![image](https://user-images.githubusercontent.com/17786332/219043145-1c75c83e-4191-45a3-acb5-775d05d13862.png)

The new edge doc:


![image](https://user-images.githubusercontent.com/17786332/219043220-1f5daf13-972e-4d56-8aaf-70ff1812863e.png)
2023-02-16 13:36:28 +01:00

200 lines
9.9 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.
### 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