@usearete/sdk 0.32.0 → 0.34.0

package/README.md

@@ -25,6 +25,37 @@ for await (const item of session.stacks.myStack.views.MyEntity.list.use()) {
 }
 ```
 
+## Authentication
+
+Pick the key by where the code runs:
+
+```ts
+// Servers, agents and local scripts (Node, Bun, Deno, workers, SSR):
+// an agent key (a4_ak_...) or secret key (a4_sk_...).
+const server = await createSession(
+  { stacks: { myStack: MY_STACK } },
+  { auth: { secretKey: process.env.ARETE_API_KEY } },
+);
+
+// Anything shipped to a browser: an origin-bound publishable key (a4_pk_...).
+// Create one with `a4 auth keys create-publishable --origin <scheme://host[:port]>`.
+const browser = await createSession(
+  { stacks: { myStack: MY_STACK } },
+  { auth: { publishableKey: import.meta.env.VITE_ARETE_PUBLISHABLE_KEY } },
+);
+```
+
+Outside a browser, when no `auth` option is set, the SDK uses `ARETE_API_KEY`
+if it is set, and otherwise the agent or secret key from your `a4` login
+(`a4 auth login`, `a4 auth signup` or `a4 init`). So `createSession({ stacks })`
+is enough in a script on a machine where you are logged in with `a4`. The login
+is read in Node (20.16+ / 22.3+), Bun and Deno (only with read permission
+already granted), never in a browser, and browser bundles contain no Node
+imports for it. If several `a4` profiles hold a key, set `ARETE_PROFILE` to pick
+one. `secretKey` throws in a browser, as does a secret or agent key passed as
+`publishableKey`; a publishable key passed as `secretKey` is refused everywhere.
+Keys are never included in error messages or logs.
+
 ## SDK Shapes
 
 ### Mental Model