From 37c93404993d6ca3be0300ca76e8c45099e7cd60 Mon Sep 17 00:00:00 2001
From: jeremystretch <jstretch@ns1.com>
Date: Fri, 11 Jun 2021 16:12:25 -0400
Subject: [PATCH] Docs and release notes for #5264

---
 docs/release-notes/version-3.0.md | 19 ++++++++++++++
 docs/rest-api/authentication.md   | 42 +++++++++++++++++++++++++++++--
 2 files changed, 59 insertions(+), 2 deletions(-)

diff --git a/docs/release-notes/version-3.0.md b/docs/release-notes/version-3.0.md
index 2faf14c80..7674d57a6 100644
--- a/docs/release-notes/version-3.0.md
+++ b/docs/release-notes/version-3.0.md
@@ -8,6 +8,23 @@
 
 ### New Features
 
+### REST API Token Provisioning ([#5264](https://github.com/netbox-community/netbox/issues/5264))
+
+This release introduces the `/api/users/tokens/` REST API endpoint, which includes a child endpoint that can be employed by a user to provision a new REST API token. This allows a user to gain REST API access without needing to first create a token via the web UI.
+
+```
+$ curl -X POST \
+-H "Content-Type: application/json" \
+-H "Accept: application/json; indent=4" \
+https://netbox/api/users/tokens/provision/
+{
+    "username": "hankhill",
+    "password: "I<3C3H8",
+}
+```
+
+If the supplied credentials are valid, NetBox will create and return a new token for the user.
+
 #### Custom Model Validation ([#5963](https://github.com/netbox-community/netbox/issues/5963))
 
 This release introduces the [`CUSTOM_VALIDATORS`](../configuration/optional-settings.md#custom_validators) configuration parameter, which allows administrators to map NetBox models to custom validator classes to enforce custom validation logic. For example, the following configuration requires every site to have a name of at least ten characters and a description:
@@ -50,6 +67,8 @@ CustomValidator can also be subclassed to enforce more complex logic by overridi
 
 ### REST API Changes
 
+* Added the `/api/users/tokens/` endpoint
+    * The `provision/` child endpoint can be used to provision new REST API tokens by supplying a valid username and password
 * dcim.Cable
     * `length` is now a decimal value
 * dcim.Device
diff --git a/docs/rest-api/authentication.md b/docs/rest-api/authentication.md
index 7fb789e0f..246896233 100644
--- a/docs/rest-api/authentication.md
+++ b/docs/rest-api/authentication.md
@@ -11,7 +11,7 @@ An authentication token is attached to a request by setting the `Authorization`
 ```
 $ curl -H "Authorization: Token $TOKEN" \
 -H "Accept: application/json; indent=4" \
-http://netbox/api/dcim/sites/
+https://netbox/api/dcim/sites/
 {
     "count": 10,
     "next": null,
@@ -23,8 +23,46 @@ http://netbox/api/dcim/sites/
 A token is not required for read-only operations which have been exempted from permissions enforcement (using the [`EXEMPT_VIEW_PERMISSIONS`](../configuration/optional-settings.md#exempt_view_permissions) configuration parameter). However, if a token _is_ required but not present in a request, the API will return a 403 (Forbidden) response:
 
 ```
-$ curl http://netbox/api/dcim/sites/
+$ curl https://netbox/api/dcim/sites/
 {
     "detail": "Authentication credentials were not provided."
 }
 ```
+
+## Initial Token Provisioning
+
+Ideally, each user should provision his or her own REST API token(s) via the web UI. However, you may encounter where a token must be created by a user via the REST API itself. NetBox provides a special endpoint to provision tokens using a valid username and password combination.
+
+To provision a token via the REST API, make a `POST` request to the `/api/users/tokens/provision/` endpoint:
+
+```
+$ curl -X POST \
+-H "Content-Type: application/json" \
+-H "Accept: application/json; indent=4" \
+https://netbox/api/users/tokens/provision/
+{
+    "username": "hankhill",
+    "password: "I<3C3H8",
+}
+```
+
+Note that we are _not_ passing an existing REST API token with this request. If the supplied credentials are valid, a new REST API token will be automatically created for the user. Note that the key will be automatically generated, and write ability will be enabled.
+
+```json
+{
+    "id": 6,
+    "url": "https://netbox/api/users/tokens/6/",
+    "display": "3c9cb9 (hankhill)",
+    "user": {
+        "id": 2,
+        "url": "https://netbox/api/users/users/2/",
+        "display": "hankhill",
+        "username": "hankhill"
+    },
+    "created": "2021-06-11T20:09:13.339367Z",
+    "expires": null,
+    "key": "9fc9b897abec9ada2da6aec9dbc34596293c9cb9",
+    "write_enabled": true,
+    "description": ""
+}
+```