diff --git a/.gitignore b/.gitignore index 4ab27b404f..4721527221 100644 --- a/.gitignore +++ b/.gitignore @@ -3,6 +3,7 @@ lerna-debug npm-debug .DS_Store /dist +website/docs/reference/api/**/sidebar.js # Logs logs @@ -50,4 +51,4 @@ package-lock.json /website/i18n/* .env -#report.json +#report.json \ No newline at end of file diff --git a/website/docs/advanced/api_access.md b/website/docs/advanced/api_access.md index 59a1062562..b3dbb0d483 100644 --- a/website/docs/advanced/api_access.md +++ b/website/docs/advanced/api_access.md @@ -7,7 +7,7 @@ It is possible to integrate directly with the Admin API. In this guide we will e ## Step 1: Create API token {#step-1-create-api-token} -Please refer to [_how to create API tokens_](../user_guide/api-token) on how to create an API token. You'll need a token with `Admin` level access for this to work. +You'll need either an [admin token](../reference/api-tokens-and-client-keys.mdx#admin-tokens) or a [personal access token](../reference/api-tokens-and-client-keys.mdx#personal-access-tokens) for this to work. To create one, follow the steps in the [_how to create API tokens_](../user_guide/token.mdx) guide or the [_how to create personal access tokens_](how-to/how-to-create-personal-access-tokens) guide, respectively. Please note that it may take up to 60 seconds for the new key to propagate to all Unleash instances due to eager caching. @@ -25,7 +25,7 @@ In the example below we will use the [Unleash Admin API](../api/admin/features) ```sh curl -X POST -H "Content-Type: application/json" \ - -H "Authorization: admintoken" \ + -H "Authorization: some-token" \ https://app.unleash-hosted.com/demo/api/admin/features/Demo/toggle/on ``` diff --git a/website/docs/how-to/how-to-create-personal-access-tokens.mdx b/website/docs/how-to/how-to-create-personal-access-tokens.mdx new file mode 100644 index 0000000000..4d1602e9ad --- /dev/null +++ b/website/docs/how-to/how-to-create-personal-access-tokens.mdx @@ -0,0 +1,41 @@ +--- +title: How to create Personal Access Tokens +--- + +:::info availability + +Personal access tokens are planned to be released in **Unleash 4.17**. + +::: + +Personal access tokens are a tool to enable a user to use the Admin API as themselves with their own set of permissions, rather than using an admin token. See [_how to use the Admin API_](../advanced/api_access) for more information. + +## Step 1: Navigate to the personal access tokens page {#step-1} + +Open the user profile pane in the admin UI and select the _view user profile_ menu item (available at the URL `/profile`). + +![The admin UI navigation "user profile" menu with the view user profile menu item selected.](/img/create-pat-1.png) + +Select the "Personal Access Tokens" menu item. + +![The user profile page with the "Personal Access Tokens" menu item highlighted.](/img/create-pat-2.png) + +## Step 2: Navigate to New Token {#step-2} + +Navigate to "New Token". + +![The New Token element highlighted. ](/img/create-pat-3.png) + +## Step 3: Fill in the create personal API token form and create it {#step-3} + +Give your token a description and optionally set an expiry date. By default the expiry date is set to 30 days. + +![The New Token form with the description text box and create element highlighted. ](/img/create-pat-4.png) + +## Step 4: Save your token {#step-4} + +Once your new token is created, the popup will display the new token details. You must save your token somewhere outside of Unleash, you won't be able to access it again. + +![The token created popup with the "Copy Token" element highlighted. ](/img/create-pat-5.png) + +Your personal access token can now be used in place of an [admin token](../reference/api-tokens-and-client-keys#admin-tokens). \ No newline at end of file diff --git a/website/docs/reference/api-tokens-and-client-keys.mdx b/website/docs/reference/api-tokens-and-client-keys.mdx index 7822b91d2c..299a8a41bd 100644 --- a/website/docs/reference/api-tokens-and-client-keys.mdx +++ b/website/docs/reference/api-tokens-and-client-keys.mdx @@ -18,9 +18,10 @@ This section describes what API tokens are. For information on how to create the ::: -Use API tokens to connect to the Unleash server API. API tokens come in three distinct types: +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) @@ -28,15 +29,17 @@ All types use [the same format](#format) but have different intended uses. Admin ### The parts of an API token {#token-data} -An API token contains the following pieces of information: +Admin, client and front-end tokens contain the following pieces of information: | Name | Description | | --- | --- | -| Token name (sometimes called "username") | The token's name. Names or **not** required to be unique. | +| 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](../user_guide/rbac.md#core-principles)). @@ -52,6 +55,24 @@ Do **not** use admin tokens for: 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. + +All personal access tokens have a lifetime and **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 + +Do **not** use personal access 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. +- Write custom Unleash UIs: Personal access tokens have a lifetime and will expire, use [admin tokens](#admin-tokens) tokens instead. + ### Client 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: @@ -127,6 +148,8 @@ The **environment** is the name of an environment on your Unleash server, such a 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": @@ -141,6 +164,10 @@ Some example client tokens are: ``` *:development.be44368985f7fb3237c584ef86f3d6bdada42ddbd63a019d26955178 ``` +- A personal access token: + ``` + user:be7536c3a160ff15e3a92da45de531dd54bc1ae15d8455c0476f086b + ``` ## Proxy client keys {#proxy-client-keys} diff --git a/website/docs/user_guide/token.mdx b/website/docs/user_guide/token.mdx index aaa715633b..3f91966760 100644 --- a/website/docs/user_guide/token.mdx +++ b/website/docs/user_guide/token.mdx @@ -5,7 +5,7 @@ title: How to create API Tokens import newTokenImage from '/img/admin_create_token_form.png'; -::: info Permissions +:::info Permissions Creating API tokens requires you to have the `CREATE_API_TOKEN` permission. This means that, as of now, **only instance admins can create API tokens.** diff --git a/website/sidebars.js b/website/sidebars.js index 9a10dd8b92..527b4599ca 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -50,6 +50,7 @@ module.exports = { label: 'Unleash API guides', items: [ 'user_guide/api-token', + 'how-to/how-to-create-personal-access-tokens', 'advanced/api_access', 'how-to/how-to-enable-openapi', ], diff --git a/website/static/img/create-pat-1.png b/website/static/img/create-pat-1.png new file mode 100644 index 0000000000..eb590c739d Binary files /dev/null and b/website/static/img/create-pat-1.png differ diff --git a/website/static/img/create-pat-2.png b/website/static/img/create-pat-2.png new file mode 100644 index 0000000000..55637d5f99 Binary files /dev/null and b/website/static/img/create-pat-2.png differ diff --git a/website/static/img/create-pat-3.png b/website/static/img/create-pat-3.png new file mode 100644 index 0000000000..d6e50cf357 Binary files /dev/null and b/website/static/img/create-pat-3.png differ diff --git a/website/static/img/create-pat-4.png b/website/static/img/create-pat-4.png new file mode 100644 index 0000000000..f7e1d52c50 Binary files /dev/null and b/website/static/img/create-pat-4.png differ diff --git a/website/static/img/create-pat-5.png b/website/static/img/create-pat-5.png new file mode 100644 index 0000000000..3b39269a95 Binary files /dev/null and b/website/static/img/create-pat-5.png differ