Merge pull request #228 from Infisical/expand-open-api

Add images to API reference authentication for getting API keys and n…

docs/api-reference/endpoints/secrets/create.mdx

@@ -2,3 +2,10 @@
 title: "Create"
 openapi: "POST /api/v2/secrets/"
 ---
+
+<Tip>
+  Using this route requires understanding Infisical's system and cryptography.
+  It may be helpful to read through the
+  [introduction](/api-reference/overview/introduction) and [guide for creating
+  secrets](/api-reference/overview/examples/create-secrets).
+</Tip>

docs/api-reference/endpoints/secrets/read.mdx

@@ -2,3 +2,10 @@
 title: "Retrieve"
 openapi: "GET /api/v2/secrets/"
 ---
+
+<Tip>
+  Using this route requires understanding Infisical's system and cryptography.
+  It may be helpful to read through the
+  [introduction](/api-reference/overview/introduction) and [guide for retrieving
+  secrets](/api-reference/overview/examples/retrieve-secrets).
+</Tip>

docs/api-reference/endpoints/secrets/update.mdx

@@ -2,3 +2,10 @@
 title: "Update"
 openapi: "PATCH /api/v2/secrets/"
 ---
+
+<Tip>
+  Using this route requires understanding Infisical's system and cryptography.
+  It may be helpful to read through the
+  [introduction](/api-reference/overview/introduction) and [guide for updating
+  secrets](/api-reference/overview/examples/update-secrets).
+</Tip>

docs/api-reference/overview/authentication.mdx

@@ -2,10 +2,14 @@
 title: "Authentication"
 ---
 
-To authenticate requests with Infisical, you must include an API key in the `X-API-KEY` header of HTTP requests made to the platform. You can obtain an API key from your user settings.
+To authenticate requests with Infisical, you must include an API key in the `X-API-KEY` header of HTTP requests made to the platform. You can obtain an API key in User Settings > API Keys
+
+![API key dashboard](../../images/api-key-dashboard.png)
+![API key in personal settings](../../images/api-key-settings.png)
+![Adding an API key](../../images/api-key-add.png)
 
 <Info>
   It's important to keep your API key secure, as it grants access to your
-  secrets in Infisical. For added security, consider rotating your API key on a
-  regular basis.
+  secrets in Infisical. For added security, set a reasonable expiration time and
+  rotate your API key on a regular basis.
 </Info>

docs/api-reference/overview/examples/create-secrets.mdx

@@ -11,12 +11,12 @@ Prerequisites:
 
 ## Flow
 
-1. Get your (encrypted) private key.
+1. [Get your (encrypted) private key](/api-reference/endpoints/users/me).
 2. Decrypt your (encrypted) private key with your password.
-3. Get the (encrypted) project key for the project.
+3. [Get the (encrypted) project key for the project.](/api-reference/endpoints/workspaces/workspace-key)
 4. Decrypt the (encrypted) project key with your private key.
 5. Encrypt your secret(s) with the project key.
-6. Send (encrypted) secret(s) to the Infical API
+6. [Send (encrypted) secret(s) to the Infical API](/api-reference/endpoints/secrets/create)
 
 ## Example
 

docs/api-reference/overview/examples/retrieve-secrets.mdx

@@ -11,11 +11,11 @@ Prerequisites:
 
 ## Flow
 
-1. Get your (encrypted) private key.
+1. [Get your (encrypted) private key.](/api-reference/endpoints/users/me)
 2. Decrypt your (encrypted) private key with your password.
-3. Get the (encrypted) project key for the project.
+3. [Get the (encrypted) project key for the project.](/api-reference/endpoints/workspaces/workspace-key)
 4. Decrypt the (encrypted) project key with your private key.
-5. Get secrets for a project and environment.
+5. [Get secrets for a project and environment.](/api-reference/endpoints/secrets/read)
 6. Decrypt the (encrypted) secrets
 
 ## Example

docs/api-reference/overview/examples/update-secrets.mdx

@@ -11,12 +11,12 @@ Prerequisites:
 
 ## Flow
 
-1. Get your (encrypted) private key.
+1. [Get your (encrypted) private key.](/api-reference/endpoints/users/me)
 2. Decrypt your (encrypted) private key with your password.
-3. Get the project key for the project.
-4. Decrypt the project key with your private key.
+3. [Get the (encrypted) project key for the project.](/api-reference/endpoints/workspaces/workspace-key)
+4. Decrypt the (encrypted) project key with your private key.
 5. Encrypt your secret(s) with the project key.
-6. Send (encrypted) updated secret(s) to the Infical API
+6. [Send (encrypted) updated secret(s) to the Infical API.](/api-reference/endpoints/secrets/update)
 
 ## Example
 

docs/api-reference/overview/introduction.mdx

@@ -2,11 +2,6 @@
 title: "Introduction"
 ---
 
-<Warning>
-  Infisical's REST API is currently unavailable and scheduled to go live on Jan
-  16!
-</Warning>
-
 Infisical's REST API provides users an alternative way to programmatically access and manage
 secrets via HTTPS requests. This can be useful for automating tasks, such as
 rotating credentials, or for integrating secret management into a larger system.
@@ -24,8 +19,9 @@ Using Infisical's API to manage secrets requires a basic understanding of the sy
 - Infisical uses AES256-GCM and [TweetNaCl.js](https://tweetnacl.js.org/#/) for symmetric and asymmetric encryption/decryption operations.
 
 <Info>
-  Infisical's system ensures greater security such that secrets are
-  encrypted/decrypted on the client-side but requires users to properly
-  implement cryptographic operations to maintain end-to-end encryption (E2EE).
-  We're
+  Infisical's system requires that secrets be encrypted/decrypted on the
+  client-side to maintain E2EE. We strongly recommend you read up on the system
+  prior to using the Infisical API. The (opt-in) ability to retrieve secrets
+  back in decrypted format if you choose to share secrets with Infisical is on
+  our roadmap.
 </Info>