docs: deployment API key lifecycle + reserved env vars

apps/deploy.mdx

@@ -65,6 +65,31 @@ kernel deploy my_app.py --env-file .env
 ```
 </CodeGroup>
 
+### Reserved environment variables
+
+Kernel injects a few environment variables into every deployment and its invocations. These names are **reserved** — if you set them via `--env` or `--env-file`, Kernel overrides your value, so setting them has no effect:
+
+- `KERNEL_API_KEY` — each deployment is given its own deployment-scoped API key at deploy time (see [Deployment API keys](/info/api-keys#deployment-api-keys)). The SDKs read this from the environment by default, so your app is already authenticated as itself. Passing your own `KERNEL_API_KEY` does **not** replace it.
+- `ENTRYPOINT_RELPATH` — set by the platform to locate your entrypoint.
+
+If your app needs a different, long-lived key (for example an org- or project-scoped key), pass it under a **non-reserved** name and read it explicitly:
+
+<CodeGroup>
+```python Python
+import os
+from kernel import Kernel
+
+# Use your own key from a non-reserved var instead of the injected deployment key.
+client = Kernel(api_key=os.environ["MY_KERNEL_API_KEY"])
+```
+
+```typescript TypeScript
+import Kernel from '@onkernel/sdk';
+
+const client = new Kernel({ apiKey: process.env.MY_KERNEL_API_KEY });
+```
+</CodeGroup>
+
 ## Deployment notes
 
 - **The dependency manifest (`package.json` for JS/TS, `pyproject.toml` for Python) must be present in the root directory of your project.**

info/api-keys.mdx

@@ -88,6 +88,18 @@ func main() {
 ```
 </CodeGroup>
 
+## Deployment API keys
+
+When you deploy an app, Kernel mints a **deployment-scoped API key** for that deployment and injects it into the deployment (and every invocation it runs) as the `KERNEL_API_KEY` environment variable. Because the SDKs read `KERNEL_API_KEY` from the environment by default, your app can call the Kernel API as itself without you managing a key.
+
+Key points about deployment keys:
+
+- **One key per deployment.** Each deploy (including a redeploy of the same app) mints a fresh deployment key. `KERNEL_API_KEY` is a [reserved environment variable](/apps/deploy#reserved-environment-variables) — a value you supply at deploy time is overridden by the injected key. To use your own long-lived key, pass it under a non-reserved name.
+- **Lifecycle tied to the deployment.** A deployment key stays valid while its deployment is active. When you redeploy, the new deployment supersedes the old one, and the old deployment's key is released once it is no longer needed — that is, once the superseded deployment is stopped **and** no invocation is still running on it.
+- **In-flight invocations are drained, not cut off.** If an invocation is still running on a deployment that gets superseded, its key is kept valid until that invocation completes; the key is released right after. An idle redeploy (nothing in flight) releases the old key immediately. In the rare case where an invocation's workflow terminates without releasing the key, a background sweep releases it after a grace period (~95 minutes). You do not need to manage any of this — it is automatic.
+
+If you need a credential whose lifetime you control (for CI, a persistent backend, or sharing across deployments), create an org- or project-scoped key as described below and reference it explicitly rather than relying on the injected `KERNEL_API_KEY`.
+
 ## List and inspect API keys
 
 List keys to audit what exists. List and retrieve responses include `masked_key`, `project_id`, `project_name`, `created_by`, and expiry metadata, but they don't include the plaintext key.