Continue api-reference docs

docs/api-reference/overview/authentication.mdx

@@ -1,3 +1,11 @@
 ---
 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.
+
+<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.
+</Info>

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

@@ -0,0 +1,64 @@
+---
+title: "Create secrets"
+---
+
+In this example, we demonstrate how to add secrets to a project and environment.
+
+Prerequisites:
+
+- Set up and add envars to [Infisical Cloud](https://app.infisical.com)
+- Grasp a basic understanding of the system and its underlying cryptography [here](/api-reference/overview/introduction).
+
+## Flow
+
+1. Get your (encrypted) private key.
+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.
+5. Encrypt your secrets with the project key.
+6. Send (encrypted) secrets to the Infical API
+
+## Example
+
+```js
+const axios = require("axios");
+const aes = require("aes-256-gcm");
+const nacl = require("tweetnacl");
+nacl.util = require("tweetnacl-util");
+
+const WORKSPACE_KEY = "3a7a243eb62078c13f09203e75e8cb32";
+
+const secretKey = "SOME_KEY";
+const secretValue = "SOME_VALUE";
+
+// encrypt key of secret
+const {
+  ciphertext: secretKeyCiphertext,
+  iv: secretKeyIV,
+  tag: secretKeyTag,
+} = aes.encrypt(secretKey, WORKSPACE_KEY);
+
+// encrypt value of secret
+const {
+  ciphertext: secretValueCiphertext,
+  iv: secretValueIV,
+  tag: secretValueTag,
+} = aes.encrypt(secretKey, WORKSPACE_KEY);
+
+// construct request body
+const secret = {
+  secretKeyCiphertext,
+  secretKeyIV,
+  secretKeyTag,
+  secretValueCiphertext,
+  secretValueIV,
+  secretValueTag,
+};
+```
+
+<Info>
+  This example uses [TweetNaCl.js](https://tweetnacl.js.org/#/), a port of
+  TweetNacl/Nacl, to perform asymmeric decryption of the project key but there
+  are ports of NaCl in every major language.
+
+</Info>

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

@@ -0,0 +1,10 @@
+---
+title: "Retrieve secrets"
+---
+
+1. Get your (encrypted) private key.
+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.
+5. Get secrets for a project and environment.
+6. Decrypt the secrets in your project.

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

@@ -0,0 +1,10 @@
+---
+title: "Update secrets"
+---
+
+1. Get your (encrypted) private key.
+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.
+5. Encrypt your secrets with the project key.
+6. Send (encrypted) updated secrets to the Infical API

docs/api-reference/overview/introduction.mdx

@@ -1,3 +1,19 @@
 ---
 title: "Introduction"
 ---
+
+Infisical's REST API provides users an alternative way to programmatically access and manage
+secrets via HTTP requests. This can be useful for automating tasks, such as
+rotating credentials, or for integrating secret management into a larger system.
+
+With the REST API, users can create, read, update, and delete secrets, as well as manage access control, query audit logs, and more.
+
+## Concepts
+
+Using Infisical's API to manage secrets requires a basic understanding of the system and its underlying cryptography detailed [here](/security/overview).
+
+- Each user has a public/private key pair that is stored with the platform; private keys are encrypted locally by the user's password before being sent off to the server during the account signup process.
+- Each (encrypted) secret belongs to a project and environment.
+- Each project has an (encrypted) project key used to encrypt the secrets within that project; Infisical stores copies of the project key, for each member of that project, encrypted under each member's public key.
+- Secrets are encrypted symmetrically by your copy of the project key belonging to the project containing.
+- Infisical uses AES256-GCM and [TweetNaCl.js](https://tweetnacl.js.org/#/) for symmetric and asymmetric encryption/decryption operations.

docs/api-reference/overview/usage.mdx

@@ -0,0 +1,18 @@
+---
+title: "Usage"
+---
+
+Prerequisites:
+
+- Set up and add envars to [Infisical Cloud](https://app.infisical.com) or your self-hosted instance.
+- Obtain an API Key in your user settings to be included in requests to the Infisical API.
+
+Using Infisical's API to manage secrets requires a basic understanding of the system and its underlying cryptography detailed [here](/security/overview).
+
+## Concepts
+
+- Each user has a public/private key pair that is stored with the platform; private keys are encrypted locally by the user's password before being sent off to the server during the account signup process.
+- Each (encrypted) secret belongs to a project and environment.
+- Each project has an (encrypted) project key used to encrypt the secrets within that project; Infisical stores copies of the project key, for each member of that project, encrypted under each member's public key.
+- Secrets are encrypted symmetrically by your copy of the project key belonging to the project containing.
+- Infisical uses AES256-GCM and [TweetNaCl.js](https://tweetnacl.js.org/#/) for symmetric and asymmetric encryption/decryption operations.