From b33fd0118236201ca7459695bee547ecb1b64afa Mon Sep 17 00:00:00 2001
From: Mo Elzubeir <elzubeir@gmail.com>
Date: Fri, 29 May 2026 14:47:41 -0500
Subject: [PATCH] docs: explain API key provisioning

---
 README.md                     |  6 ++++++
 sdks/javascript/README.md     | 24 ++++++++++++++++++++++++
 sdks/javascript/docs/API.md   |  2 ++
 sdks/javascript/docs/GUIDE.md | 12 ++++++++++++
 4 files changed, 44 insertions(+)

diff --git a/README.md b/README.md
index c56da7f..122d00b 100644
--- a/README.md
+++ b/README.md
@@ -10,6 +10,12 @@ Future SDKs can live beside it, e.g. `sdks/python`, `sdks/go`, or `sdks/php`.
 
 ## JavaScript / TypeScript
 
+API keys are provisioned by Socialhose or your account administrator. Set the key server-side before using the SDK:
+
+```bash
+export SOCIALHOSE_API_KEY="sh_your_key_here"
+```
+
 ```bash
 npm install @socialhose/api
 ```
diff --git a/sdks/javascript/README.md b/sdks/javascript/README.md
index 8c37fda..e68e5ac 100644
--- a/sdks/javascript/README.md
+++ b/sdks/javascript/README.md
@@ -28,6 +28,30 @@ Use `@socialhose/api` from server-side JavaScript/TypeScript to build:
 
 This package is intended for **backend code only**. Do not ship your Socialhose API key to browsers.
 
+## Getting an API key
+
+API keys are issued by Socialhose. The SDK does not create keys, and there is no self-service key-generation flow documented in this package.
+
+To use the SDK:
+
+1. Request Socialhose Public API access from the Socialhose team or your account administrator.
+2. Ask for an API key with access to the campaigns you need to query.
+3. Store it as a server-side environment variable:
+
+```bash
+export SOCIALHOSE_API_KEY="sh_your_key_here"
+```
+
+4. Pass it to the client:
+
+```ts
+const socialhose = new SocialhoseClient({
+  apiKey: process.env.SOCIALHOSE_API_KEY!,
+});
+```
+
+Do not commit API keys, expose them in frontend bundles, or send them to browsers. If you are building a web app, call Socialhose from your server/API route and return only the data your frontend needs.
+
 ## Install
 
 ```bash
diff --git a/sdks/javascript/docs/API.md b/sdks/javascript/docs/API.md
index 774cd06..30a3764 100644
--- a/sdks/javascript/docs/API.md
+++ b/sdks/javascript/docs/API.md
@@ -66,6 +66,8 @@ Type exports:
 
 ## Authentication
 
+Socialhose API keys are provisioned by Socialhose or by your account administrator. This SDK consumes an existing key; it does not create or manage keys.
+
 Every request sends:
 
 - `Authorization: Api-Key <apiKey>`
diff --git a/sdks/javascript/docs/GUIDE.md b/sdks/javascript/docs/GUIDE.md
index e29c274..c02de57 100644
--- a/sdks/javascript/docs/GUIDE.md
+++ b/sdks/javascript/docs/GUIDE.md
@@ -20,6 +20,18 @@ npm install @socialhose/api
 
 Requires Node 18+ or a custom `fetch` implementation.
 
+## Getting API access
+
+Socialhose API keys are provisioned by Socialhose. This SDK only consumes an existing key; it cannot create, rotate, or discover keys for you.
+
+Ask the Socialhose team or your account administrator for a Public API key and confirm which campaigns it can access. Then set it in your server environment:
+
+```bash
+export SOCIALHOSE_API_KEY="sh_your_key_here"
+```
+
+Keep this value server-side. For browser applications, create your own backend endpoint that uses this SDK and returns sanitized data to the frontend.
+
 ## Basic setup
 
 ```ts