From be4de289a17d949aa08b8bfadd5b0a8a7997e0d6 Mon Sep 17 00:00:00 2001
From: andreas-unleash <andreas@getunleash.ai>
Date: Thu, 13 Apr 2023 11:08:54 +0300
Subject: [PATCH] fix: project api token docs (#3485)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

<!-- Thanks for creating a PR! To make it easier for reviewers and
everyone else to understand what your changes relate to, please add some
relevant content to the headings below. Feel free to ignore or delete
sections that you don't think are relevant. Thank you! ❤️ -->
[Previous PR (has the
comments)](https://github.com/Unleash/unleash/pull/3405)

## About the changes
<!-- Describe the changes introduced. What are they and why are they
being introduced? Feel free to also add screenshots or steps to view the
changes if they're visual. -->

<!-- Does it close an issue? Multiple? -->
Closes #

<!-- (For internal contributors): Does it relate to an issue on public
roadmap? -->
<!--
Relates to [roadmap](https://github.com/orgs/Unleash/projects/10) item:
#
-->

### Important files
<!-- PRs can contain a lot of changes, but not all changes are equally
important. Where should a reviewer start looking to get an overview of
the changes? Are any files particularly important? -->


## Discussion points
<!-- Anything about the PR you'd like to discuss before it gets merged?
Got any questions or doubts? -->

---------

Signed-off-by: andreas-unleash <andreas@getunleash.ai>
Co-authored-by: Thomas Heartman <thomas@getunleash.ai>
---
 .../reference/api-tokens-and-client-keys.mdx  | 22 ++++++++++++-------
 1 file changed, 14 insertions(+), 8 deletions(-)

diff --git a/website/docs/reference/api-tokens-and-client-keys.mdx b/website/docs/reference/api-tokens-and-client-keys.mdx
index 20a2a77f14..0ff3f1b173 100644
--- a/website/docs/reference/api-tokens-and-client-keys.mdx
+++ b/website/docs/reference/api-tokens-and-client-keys.mdx
@@ -21,7 +21,6 @@ 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 four distinct types:
 
 -   [Admin tokens](#admin-tokens)
--   [Project level access tokens](#project-level-access-tokens)
 -   [Personal access tokens](#personal-access-tokens)
 -   [Client tokens](#client-tokens)
 -   [Front-end tokens](#front-end-tokens)
@@ -41,6 +40,20 @@ Admin, client and front-end tokens contain the following pieces of information:
 
 Personal access tokens follow their own special format, and only contain an optional description for the token and an expiry date.
 
+
+### API token visibility
+
+:::info project-level visibility
+
+Project-level visibility and access to API tokens was introduced in Unleash 4.22.
+
+:::
+
+By default, only admin users can create API tokens, and only admins can see their values.
+
+However, any [client](#client-tokens client tokens) and [front-end tokens](#front-end-tokens) that are applicable to a project, will also be visible to any members of that project that have the `READ_PROJECT_API_TOKEN` permission (all project members by default). 
+
+Similarly, any project members with the `CREATE_PROJECT_API_TOKEN` permission can also create client and front-end tokens for that specific project ([how to create project API tokens](../how-to/how-to-create-project-api-tokens.mdx)).
 ### 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)).
@@ -57,15 +70,8 @@ Do **not** use admin tokens for:
 Support for scoped admin tokens with more fine-grained permissions is currently in the planning stage.
 
 
-### Project level access tokens
 
-All project members can see any `CLIENT` (server-side client token) and `FRONTEND` (client-side client token) respectively.
 
-Use personal access tokens to:
-
-- Provide more fine-grained permissions for automation than an admin token provides
-- Give access to all project members (or anyone with `READ_PROJECT_API_TOKEN` permission) to read the token
-- Give access to the project owner (or anyone with `CREATE_PROJECT_API_TOKEN` permission) to create a token,
 
 
 ### Personal access tokens