Mirrors/unleash.unleash
1
0
Fork 0
mirror of https://github.com/Unleash/unleash.git synced 2025-02-04 00:18:01 +01:00
Code Issues Projects Releases Wiki Activity

Add diagram for connecting SDK to Edge to Unleash

Browse Source
This commit is contained in:
melindafekete 2025-02-03 16:08:36 +01:00
parent c947e7b003
commit e80f3611b0
No known key found for this signature in database
2 changed files with 39 additions and 26 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

65
website/docs/reference/api-tokens-and-client-keys.mdx
View File

@ -3,37 +3,41 @@ title: API Tokens and Client Keys
pagination_next: reference/front-end-api pagination_next: reference/front-end-api
--- ---
Unleash uses API keys to facilitate communication between consuming clients such as [SDKs](../reference/sdks), [Edge](../reference/unleash-edge), or other tools and automation. ## Overview
Unleash uses API keys to facilitate communication between consuming clients such as [SDKs](../reference/sdks), [Unleash Edge](../reference/unleash-edge), or other tools and automation.
Unleash supports the following types of API tokens: Unleash supports the following types of API tokens:
- [Client tokens](#client-tokens) for connecting server-side client SDKs, Unleash Edge, and Unleash Proxy to Unleash. - [Client tokens](#client-tokens) for connecting [server-side client SDKs](../reference/sdks#server-side-sdks), [Unleash Edge](../reference/unleash-edge), and [Unleash Proxy](../reference/unleash-proxy) to Unleash.
- [Frontend tokens](#frontend-tokens) for connecting client-side SDKs to Unleash using the Frontend API. - [Frontend tokens](#frontend-tokens) for connecting [client-side SDKs](../reference/sdks#front-end-sdks) to Unleash using the [Frontend API](../reference/front-end-api) or [Unleash Edge](../reference/unleash-edge).
- [Personal access tokens](#personal-access-tokens) for testing and debugging or providing temporary access to an automation tool. - [Personal access tokens](#personal-access-tokens) for testing and debugging or providing temporary access to an automation tool.
- [Service account tokens](/reference/service-accounts) for providing API access to integrations or automation tools. - [Service account tokens](/reference/service-accounts) for providing API access to integrations or automation tools.
To connect a client-side SDK to Unleash using Unleash Edge, you need both a [client](#client-tokens) and [frontend token](#frontend-tokens). See [Connect a client-side SDK to Unleash using Edge](#connect-a-client-side-sdk-to-unleash-using-edge) for an example.
## API token types ## API token types
### Client tokens ### Client tokens
Client tokens are intended for use in [server-side client SDKs](../reference/sdks#server-side-sdks) to grant the permissions to: Client tokens are intended for use in [server-side client SDKs](../reference/sdks#server-side-sdks), [Unleash Edge](../reference/unleash-edge), and [Unleash Proxy](../reference/unleash-proxy) to grant the permissions to:
- Reading feature flag information - Reading feature flag information
- Registering applications with the Unleash server - Registering applications with the Unleash server
- Sending usage metrics - Sending usage metrics
Client tokens are scoped to one or more projects and a single environment. When creating a client token, you c an 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 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. Client tokens cannot be used in frontend SDKs; use [frontend tokens](#frontend-tokens) instead.
### Frontend tokens ### 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: Use frontend tokens for connecting [frontend SDKs](../reference/sdks#front-end-sdks) to Unleash using the [Unleash Frontend API](./front-end-api) or [Unleash Edge](../reference/unleash-edge). They grant the user permission to:
- Reading enabled flags for a given context - Reading enabled flags for a given context
- Registering applications with the Unleash server - Registering applications with the Unleash server
- Sending usage metrics - 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 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. Frontend tokens cannot be used in server-side SDKs; use [client tokens](#client-tokens) instead.
### Personal access tokens ### Personal access tokens
@ -42,9 +46,9 @@ You can use personal access tokens for testing, debugging, or giving temporary a
When you use a personal access token to modify resources, the events record the token creator's name for that operation. 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 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 to follow security best practices.
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. 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.
### Service account tokens ### Service account tokens
@ -55,12 +59,12 @@ Service account tokens provide API access to integration and automation tools. T
:::warning :::warning
Admin tokens are deprecated. Use other token types: Admin tokens are deprecated. Use other token types:
- With [Open Source](https://www.getunleash.io/pricing) and [Pro](../availability#plans), use [personal access tokens](#personal-access-tokens). - 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). - 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). 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 ## API token permissions
@ -71,14 +75,14 @@ Admin tokens grant full read and write access to all resources in the Unleash se
::: :::
The following table provides a summary of what ...: The following table provides a summary of what actions different roles can perform with API tokens:
| Role/Permission | Details | | Role/Permission | Details |
|-----------------------------------------------|-------------------------------------------------------------------------| |-----------------------------------------------|-------------------------------------------------------------------------|
| Admin root role | Can view, create, update, or delete tokens for any project. | | 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. | | Custom root role with API token permission | Can view, create, update, or delete tokens for any project with the corresponding permission, such as `CREATE_CLIENT_API_TOKEN`. |
| Member project role | Can view, create, update, or delete tokens within the project. | | 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. | | Custom project role with API token permission | Can view, create, update, or delete tokens within the project with the corresponding permission, `CREATE_PROJECT_API_TOKEN`. |
| Viewer root role | Cannot view, create, update, or delete tokens. | | Viewer root role | Cannot view, create, update, or delete tokens. |
| Any role | Can create personal access tokens. | | Any role | Can create personal access tokens. |
@ -90,7 +94,7 @@ API tokens consist of three parts:
2. Environment 2. Environment
3. Hash 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 parts are separated by two delimiters: a colon (`:`) between the projects and the environment, and a period (`.`) between the environment and the hash.
``` ```
{{projects}}:{{environment}}.{{hash}} {{projects}}:{{environment}}.{{hash}}
@ -98,10 +102,10 @@ The parts are separated by two different separators: A colon (`:`) between the p
The project value of the token can be 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. - 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 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)**. - `*`: when the token is valid for all current and future projects.
The environment is the name of an environment on your Unleash instance, such as `development`. The hash is 64-character long hexadecimal string. The environment value of the token is the name of an environment on your Unleash instance, such as `development`. The hash is a 64-character-long hexadecimal string.
Personal access tokens start with the string `user`, and do not contain additional project or environment information. Personal access tokens start with the string `user`, and do not contain additional project or environment information.
@ -125,7 +129,7 @@ Some example API tokens are:
``` ```
Note, in Unleash v4.3 or less, API tokens are a 64-character long hexadecimal string with no additional information. For example: Note, in Unleash v4.3 or less, API tokens are a 64-character-long hexadecimal string with no additional information. For example:
``` ```
be44368985f7fb3237c584ef86f3d6bdada42ddbd63a019d26955178 be44368985f7fb3237c584ef86f3d6bdada42ddbd63a019d26955178
@ -134,11 +138,20 @@ be44368985f7fb3237c584ef86f3d6bdada42ddbd63a019d26955178
## Create an API token ## Create an API token
Depending on your [permissions](#api-token-permissions), you can create API tokens in the Unleash Admin UI in three ways: Depending on your [permissions](#api-token-permissions), you can create API tokens in the Unleash Admin UI in three ways:
- **Admin > API access**: for client or frontend tokens; requires the Admin root role, or a custom root role with API token permissions. - **Admin > API access**: for client or frontend tokens; requires the Admin root role, or a custom root role with [API token permissions](#api-token-permissions).
- **Settings > API access** inside a project: for project-specific client or frontend tokens; permitted for project Members or users with a [corresponding root role](#api-token-permissions). - **Settings > API access** inside a project: for project-specific client or frontend tokens; permitted for project Members or users with a [corresponding root role](#api-token-permissions).
- **Profile > View profile settings > Personal API tokens**: for personal access tokens. - **Profile > View profile settings > Personal API tokens**: for [personal access tokens](#personal-access-tokens).
## Connect a client-side SDK to Unleash using Edge
To connect a client-side SDK to Unleash using Unleash Edge, you need both a [client](#client-tokens) and [frontend token](#frontend-tokens):
- The client-side SDK needs a frontend token to communicate with Edge.
- Edge needs a client token to communicate with the Unleash server.
Ensure that the client token has at least the same project and environment scope as the frontend token.
![Diagram showing the types of tokens needed to connect a client-side SDK with Edge, and Edge with Unleash](/img/token-types-example.png)
### Create a personal access token
## Proxy client keys ## Proxy client keys
@ -148,7 +161,7 @@ Unleash Proxy is in maintenance mode. Use [Unleash Edge](../reference/unleash-ed
::: :::
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. You can 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. 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.
@ -158,4 +171,4 @@ To designate a string as a proxy client key, add it to the `clientKeys` list whe
::: :::
Proxy client keys cannot be used to connect to the Unleash API, use [API tokens](#api-tokens) instead. Proxy client keys cannot be used to connect to the Unleash API; use [API tokens](#api-tokens) instead.

BIN
website/static/img/token-types-example.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 119 KiB