From 7251b8524f81f955e13c35ab582e5f0ce5ddf1a8 Mon Sep 17 00:00:00 2001
From: Vardan Torosyan <vardants@gmail.com>
Date: Thu, 21 Jul 2022 18:56:41 +0200
Subject: [PATCH] Service accounts: Update docs to mention about reverting
 token to API key (#52608)

* Service accounts: Update docs to mention about reverting token to API key

* Update docs/sources/administration/api-keys/_index.md
---
 .../sources/administration/api-keys/_index.md | 20 ++++++--
 .../developers/http_api/serviceaccount.md     | 48 +++++++++++++------
 2 files changed, 50 insertions(+), 18 deletions(-)

diff --git a/docs/sources/administration/api-keys/_index.md b/docs/sources/administration/api-keys/_index.md
index db87e5aff97..b8f539d8b29 100644
--- a/docs/sources/administration/api-keys/_index.md
+++ b/docs/sources/administration/api-keys/_index.md
@@ -60,12 +60,24 @@ You can choose to migrate a single API key or all API keys. Note that when you m
 **To migrate all API keys to service accounts:**
 
 1. Sign in to Grafana, hover your cursor over **Configuration** (the gear icon), and click **API Keys**.
-1. In the top of the page, find the section which says **Switch from API keys to service accounts**
-1. Click **Migrate now**.
-1. Once migration is successful, you can choose to forever hide the API keys tab and use service accounts from there on. Click **Go to service accounts tab and never show API keys tab again** if you want to do that.
+2. In the top of the page, find the section which says **Switch from API keys to service accounts**
+3. Click **Migrate to service accounts now**.
+4. A confirmation window will appear, asking to confirm the migration. Click **Yes, migrate now** if you are willing to continue.
+5. Once migration is successful, you can choose to forever hide the API keys page. Click **Hide API keys page forever** if you want to do that.
 
 **To migrate single API key to a service account:**
 
 1. Sign in to Grafana, hover your cursor over **Configuration** (the gear icon), and click **API Keys**.
 1. Find the API Key you want to migrate.
-1. Click **Migrate**.
+1. Click **Migrate to service account**.
+
+### Revert service account token to API key
+
+**Note:** This is undesired operation and should be used only in emergency situations.
+
+It is possible to convert back service account token to API key. You can use the [Revert service account token to API key HTTP API]({{< relref "../../developers/http_api/create-api-tokens-for-org/#how-to-create-a-new-organization-and-an-api-token" >}}) for that.
+
+**The revert will perform the following actions:**
+
+1. Convert the given service account token back to API key
+1. Delete the service account associated with the given key. **Make sure there are no other tokens associated with the service account, otherwise they all will be deleted.**
diff --git a/docs/sources/developers/http_api/serviceaccount.md b/docs/sources/developers/http_api/serviceaccount.md
index 41ad0787b0f..a961f042d70 100644
--- a/docs/sources/developers/http_api/serviceaccount.md
+++ b/docs/sources/developers/http_api/serviceaccount.md
@@ -110,8 +110,6 @@ Authorization: Basic YWRtaW46YWRtaW4=
 }
 ```
 
-Requires basic authentication and that the authenticated user is a Grafana Admin.
-
 **Example Response**:
 
 ```http
@@ -153,8 +151,6 @@ Content-Type: application/json
 Authorization: Basic YWRtaW46YWRtaW4=
 ```
 
-Requires basic authentication and that the authenticated user is a Grafana Admin.
-
 **Example Response**:
 
 ```http
@@ -201,8 +197,6 @@ Authorization: Basic YWRtaW46YWRtaW4=
 }
 ```
 
-Requires basic authentication and that the authenticated user is a Grafana Admin.
-
 **Example Response**:
 
 ```http
@@ -225,8 +219,6 @@ Content-Type: application/json
 
 ---
 
-## Service account tokens
-
 ## Get service account tokens
 
 `GET /api/serviceaccounts/:id/tokens`
@@ -248,8 +240,6 @@ Content-Type: application/json
 Authorization: Basic YWRtaW46YWRtaW4=
 ```
 
-Requires basic authentication and that the authenticated user is a Grafana Admin.
-
 **Example Response**:
 
 ```http
@@ -295,8 +285,6 @@ Authorization: Basic YWRtaW46YWRtaW4=
 }
 ```
 
-Requires basic authentication and that the authenticated user is a Grafana Admin.
-
 **Example Response**:
 
 ```http
@@ -331,8 +319,6 @@ Content-Type: application/json
 Authorization: Basic YWRtaW46YWRtaW4=
 ```
 
-Requires basic authentication and that the authenticated user is a Grafana Admin.
-
 **Example Response**:
 
 ```http
@@ -343,3 +329,37 @@ Content-Type: application/json
 	"message": "API key deleted"
 }
 ```
+
+## Revert service account token to API key
+
+`DELETE /api/serviceaccounts/revert/:keyId`
+
+This operation will delete the service account and create a legacy API Key for the given `keyId`.
+
+**Required permissions**
+
+See note in the [introduction]({{< ref "#service-account-api" >}}) for an explanation.
+
+| Action                 | Scope |
+| ---------------------- | ----- |
+| serviceaccounts:delete | n/a   |
+
+**Example Request**:
+
+```http
+DELETE /api/serviceaccounts/revert/glsa_VVQjot0nijQ59lun6pMZRtsdBXxnFQ9M_77c34a79 HTTP/1.1
+Accept: application/json
+Content-Type: application/json
+Authorization: Basic YWRtaW46YWRtaW4=
+```
+
+**Example Response**:
+
+```http
+HTTP/1.1 200
+Content-Type: application/json
+
+{
+	"message": "Reverted service account to API key"
+}
+```