From 49af94334e759bc123c057708652857fae8c54b0 Mon Sep 17 00:00:00 2001
From: TrustyJAID <TrustyJAID@gmail.com>
Date: Tue, 23 Apr 2019 15:51:37 -0600
Subject: [PATCH] Add Central API Key Documentation (#2574)

---
 docs/framework_apikeys.rst | 48 ++++++++++++++++++++++++++++++++++++++
 docs/index.rst             |  1 +
 2 files changed, 49 insertions(+)
 create mode 100644 docs/framework_apikeys.rst

diff --git a/docs/framework_apikeys.rst b/docs/framework_apikeys.rst
new file mode 100644
index 000000000..5cb89e6b5
--- /dev/null
+++ b/docs/framework_apikeys.rst
@@ -0,0 +1,48 @@
+.. V3 Shared API Key Reference
+
+===============
+Shared API Keys
+===============
+
+Red has a central API key storage utilising the core bots config. This allows cog creators to add a single location to store API keys for their cogs which may be shared between other cogs.
+
+There needs to be some consistency between cog creators when using shared API keys between cogs. To help make this easier service should be all **lowercase** and the key names should match the naming convetion of the API being accessed. 
+
+Example:
+
+Twitch has a client ID and client secret so a user should be asked to input
+
+``[p]set api twitch client_id,1234ksdjf client_secret,1234aldlfkd``
+
+and when accessed in the code it should be done by 
+
+.. code-block:: python
+
+    await self.bot.db.api_tokens.get_raw("twitch", default={"client_id": None, "client_secret: None"})
+
+Each service has its own dict of key, value pairs for each required key type. If there's only one key required then a name for the key is still required for storing and accessing.
+
+Example:
+
+``[p]set api youtube api_key,1234ksdjf``
+
+and when accessed in the code it should be done by 
+
+.. code-block:: python
+
+    await self.bot.db.api_tokens.get_raw("youtube", default={"api_key": None})
+
+
+***********
+Basic Usage
+***********
+
+.. code-block:: python
+
+    class MyCog:
+        @commands.command()
+        async def youtube(self, ctx, user: str):
+            apikey = await self.bot.db.api_tokens.get_raw("youtube", default={"api_key": None})
+            if apikey["api_key"] is None:
+                return await ctx.send("The YouTube API key has not been set.")
+            # Use the API key to access content as you normally would
diff --git a/docs/index.rst b/docs/index.rst
index 8826fe389..d0af8b922 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -29,6 +29,7 @@ Welcome to Red - Discord Bot's documentation!
 
     guide_migration
     guide_cog_creation
+    framework_apikeys
     framework_bank
     framework_bot
     framework_checks