From ec321c5619fadb84f98075752ff0446ab3eb2ac5 Mon Sep 17 00:00:00 2001
From: Jamil <jamilbk@users.noreply.github.com>
Date: Fri, 13 Jan 2023 15:23:21 -0800
Subject: [PATCH] Update default REST API docs path; Note on stdout api tokens
 (#1306)

---
 apps/fz_http/test/test_helper.exs               |  2 +-
 docs/docs/administer/upgrade.mdx                |  2 +-
 .../docs/reference/{api => rest-api}/README.mdx | 17 +++++++++++++++--
 .../{api => rest-api}/configurations.mdx        |  0
 .../reference/{api => rest-api}/devices.mdx     |  0
 docs/docs/reference/{api => rest-api}/rules.mdx |  0
 docs/docs/reference/{api => rest-api}/users.mdx |  0
 7 files changed, 17 insertions(+), 4 deletions(-)
 rename docs/docs/reference/{api => rest-api}/README.mdx (51%)
 rename docs/docs/reference/{api => rest-api}/configurations.mdx (100%)
 rename docs/docs/reference/{api => rest-api}/devices.mdx (100%)
 rename docs/docs/reference/{api => rest-api}/rules.mdx (100%)
 rename docs/docs/reference/{api => rest-api}/users.mdx (100%)

diff --git a/apps/fz_http/test/test_helper.exs b/apps/fz_http/test/test_helper.exs
index 069943b97..b92293b0a 100644
--- a/apps/fz_http/test/test_helper.exs
+++ b/apps/fz_http/test/test_helper.exs
@@ -3,7 +3,7 @@ Mox.defmock(OpenIDConnect.Mock, for: OpenIDConnect.MockBehaviour)
 
 Bureaucrat.start(
   writer: Firezone.DocusaurusWriter,
-  default_path: "../../docs/docs/reference/api"
+  default_path: "../../docs/docs/reference/rest-api"
 )
 
 ExUnit.start(formatters: [ExUnit.CLIFormatter, Bureaucrat.Formatter])
diff --git a/docs/docs/administer/upgrade.mdx b/docs/docs/administer/upgrade.mdx
index b329a5c8a..60602234f 100644
--- a/docs/docs/administer/upgrade.mdx
+++ b/docs/docs/administer/upgrade.mdx
@@ -49,7 +49,7 @@ issue](https://github.com/firezone/firezone/issues/new/choose).
 
 ## Upgrading to 0.7.x
 
-Firezone 0.7.0 introduces a new [REST API](/reference/api/) that allows administrators
+Firezone 0.7.0 introduces a new [REST API](/reference/rest-api/) that allows administrators
 to automate much of the day to day configuration of Firezone.
 
 The REST API `/v0/configuration` endpoint supersedes some of the previous environment
diff --git a/docs/docs/reference/api/README.mdx b/docs/docs/reference/rest-api/README.mdx
similarity index 51%
rename from docs/docs/reference/api/README.mdx
rename to docs/docs/reference/rest-api/README.mdx
index 563416db9..e4d35cc99 100644
--- a/docs/docs/reference/api/README.mdx
+++ b/docs/docs/reference/rest-api/README.mdx
@@ -9,9 +9,22 @@ Welcome to Firezone REST API v0 documentation.
 
 To get started with the REST API, you'll first need an API token.
 This can be generated in the UI at `/settings/account` or via the CLI
-with `docker compose -f $HOME/.firezone/docker-compose.yml exec firezone bin/create-api-token`
-on your live Firezone instance.
+with:
 
+```shell
+docker compose -f $HOME/.firezone/docker-compose.yml exec firezone bin/create-api-token
+```
+
+**Note**: The token is written to `STDOUT` by default. You may wish to redirect its output
+to a file instead:
+
+```shell
+docker compose -f $HOME/.firezone/docker-compose.yml exec firezone bin/create-api-token > fz_token
+```
+
+:::caution
+API tokens generated from the CLI are owned by the primary administrator.
+:::
 
 ```mdx-code-block
 import DocCardList from '@theme/DocCardList';
diff --git a/docs/docs/reference/api/configurations.mdx b/docs/docs/reference/rest-api/configurations.mdx
similarity index 100%
rename from docs/docs/reference/api/configurations.mdx
rename to docs/docs/reference/rest-api/configurations.mdx
diff --git a/docs/docs/reference/api/devices.mdx b/docs/docs/reference/rest-api/devices.mdx
similarity index 100%
rename from docs/docs/reference/api/devices.mdx
rename to docs/docs/reference/rest-api/devices.mdx
diff --git a/docs/docs/reference/api/rules.mdx b/docs/docs/reference/rest-api/rules.mdx
similarity index 100%
rename from docs/docs/reference/api/rules.mdx
rename to docs/docs/reference/rest-api/rules.mdx
diff --git a/docs/docs/reference/api/users.mdx b/docs/docs/reference/rest-api/users.mdx
similarity index 100%
rename from docs/docs/reference/api/users.mdx
rename to docs/docs/reference/rest-api/users.mdx