From 443de41eb5136f0b8cfc4262c7481ffcb8d3ee45 Mon Sep 17 00:00:00 2001
From: paranarimasu <33796518+paranarimasu@users.noreply.github.com>
Date: Tue, 3 May 2022 12:06:24 -0500
Subject: [PATCH] feat: add documentation for token-based authentication (#17)

---
 docs/.vuepress/config.js      |  4 +++
 docs/README.md                |  6 ++++
 docs/authentication/README.md | 55 +++++++++++++++++++++++++++++++++++
 docs/ratelimiting/README.md   |  4 +++
 4 files changed, 69 insertions(+)
 create mode 100644 docs/authentication/README.md

diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js
index 4839280..0b53a11 100644
--- a/docs/.vuepress/config.js
+++ b/docs/.vuepress/config.js
@@ -17,6 +17,10 @@ module.exports = {
           {
             title: 'Rate Limiting',
             to: '/ratelimiting'
+          },
+          {
+            title: 'Authentication',
+            to: '/authentication'
           }
         ]
       },
diff --git a/docs/README.md b/docs/README.md
index e23f26c..1428264 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -22,6 +22,12 @@ The AnimeThemes API applies the standard named rate limiter of the Laravel Frame
 
 We provide an overview of managing request quotas.
 
+## [Authentication](/authentication/)
+
+The AnimeThemes API uses token-based authentication to grant the user access to protected actions.
+
+API tokens can be granted abilities that specify which actions can be performed.
+
 ## Terms of Use
 
 The AnimeThemes API applies the [**AnimeThemes Terms of Service**](/terms-of-service).
diff --git a/docs/authentication/README.md b/docs/authentication/README.md
new file mode 100644
index 0000000..7afc0f4
--- /dev/null
+++ b/docs/authentication/README.md
@@ -0,0 +1,55 @@
+---
+title: Authentication
+---
+
+# Authentication
+
+---
+
+The AnimeThemes API uses token-based authentication to grant the user access to protected actions.
+
+API tokens can be granted abilities that specify which actions can be performed.
+
+## Managing Tokens
+
+API tokens are managed from the API Tokens Screen within the AnimeThemes application.
+
+### Creating Tokens
+
+Log in to AnimeThemes. The Dashboard Screen will be displayed with a Navigation Bar.
+
+Click the User Menu in the top-right corner of the Navigation Bar. The API Tokens Option will be displayed.
+
+Select the API Tokens Option. The API Tokens Screen will be displayed.
+
+On the API Tokens Screen, the Create API Token Form will be displayed.
+
+On the Create API Token Form, specify a Token Name.
+
+On the Create API Token Form, optionally specify Permissions. Permissions are the abilities that the token is granted.
+
+On the Create API Token Form, click the Create Button. The API Token Modal will be displayed.
+
+On the API Token Modal, copy and store the token.
+
+On the API Token Modal, click the Close Button. The Modal will be dismissed and the token will be displayed in the Manage API Tokens Form.
+
+### Updating Tokens
+
+On the Manage API Tokens Form, click the Permissions Link. The API Token Permissions Modal will be displayed.
+
+On the API Token Permissions Modal, specify changes to Permissions.
+
+On the API Token Permissions Modal, click the Save Button. The Modal will be dismissed and the changes will be applied.
+
+### Deleting Tokens
+
+On the Manage API Tokens Form, click the Delete Link. The Delete API Token Modal will be displayed.
+
+On the Delete API Token Modal, click the Delete Button. The Delete API Token Modal will be dismissed and the API token will be removed from the Manage API Tokens Form.
+
+## Expiration
+
+API Tokens are configured to expire after **one month**.
+
+Expired API Tokens are automatically pruned from AnimeThemes once a day.
\ No newline at end of file
diff --git a/docs/ratelimiting/README.md b/docs/ratelimiting/README.md
index 84a663f..79ee3fd 100644
--- a/docs/ratelimiting/README.md
+++ b/docs/ratelimiting/README.md
@@ -23,6 +23,8 @@ X-RateLimit-Remaining: 89
 ...
 ```
 
+## Exceeding the Rate Limit
+
 If the rate limit is exceeded, the AnimeThemes API will return `Retry-After` and `X-RateLimit-Reset` headers in the response.
 
 ```sh
@@ -34,6 +36,8 @@ X-RateLimit-Reset: 1625073463180
 ...
 ```
 
+Additionally, the AnimeThemes API will return an error message in the response body.
+
 ```json
 {
     message: "Too Many Attempts."