docs: adds documentation for personal api tokens (#2164)

* docs: adds documentation for personal api tokens

Co-authored-by: Thomas Heartman <thomas@getunleash.ai>

.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

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
 ```
 

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).

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

@@ -18,25 +18,28 @@ 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)
 
 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}
 
-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}
 

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.**
 

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',
                     ],