Document email header fallback for provision endpoint

api-reference/agents.mdx

@@ -475,7 +475,7 @@
 
 ## Agent verification
 
 Agents can be verified using multiple verification types: `eas` (Ethereum Attestation Service), `coinbase`, `ens`, or `webauthn`.
 
 ### Get verification status
 
@@ -548,7 +548,7 @@
 
 Provisions a new agent with messaging channel tokens. No authentication is required. Rate-limited per IP. At least one channel token is required.
 
 The request is proxied to the backend provisioning service. A dedicated Mux live stream is automatically created for the agent. The backend may enqueue the provisioning job to the `provision` queue for asynchronous processing.
 
 ### Request body
 
@@ -561,9 +561,11 @@
 | `aiProvider` | string | No | AI provider (default: `openrouter`). Options: `openrouter`, `gemini`, `groq`, `anthropic`, `openai` |
 | `apiKey` | string | No | API key for the AI provider |
 | `plan` | string | No | Plan tier. Options: `solo`, `collective`, `label`, `network`. A paid plan is required — requests with `plan` set to `free` (or omitted) return `402 Payment Required`. |
-| `email` | string | No | User email address. Used for admin and tester bypass of payment enforcement. |
+| `email` | string | No | User email address. Used for admin and tester bypass of payment enforcement. Falls back to the `x-user-email` request header when not provided in the body (see below). |
 | `stripeSubscriptionId` | string | No | Active Stripe subscription ID. Required for non-admin, non-tester users on paid plans. When absent and the user is not an admin or tester, the endpoint returns `402 Payment Required`. |
 
+<Note>The `email` field can also be provided via the `x-user-email` request header. When the request body does not include `email`, the backend reads the header value instead. This is useful when the auth middleware has already resolved the user's email and forwarded it in the header.</Note>
+
 <Warning>The `free` plan value is deprecated. The provisioning service now requires a paid plan (`solo`, `collective`, `label`, or `network`) and a valid Stripe subscription. Requests with `plan` set to `free` return `402 Payment Required` with `code: "PAYMENT_REQUIRED"`.</Warning>
 
 <Warning>The following request fields are deprecated and no longer accepted: `whatsappPhoneNumberId`, `whatsappBusinessAccountId`, `discordGuildId`, `discordChannelId`.</Warning>
@@ -583,7 +585,7 @@
 }
 ```
 
 <Note>The `/api/provision` proxy returns only `success`, `userId`, `subdomain`, `url`, `streamKey`, and `liveStreamId`. The full response shape from the backend provisioning service is shown below.</Note>
 
 ### Full backend response
 
@@ -642,6 +644,7 @@
 | 429 | Too many requests |
 | 500 | Internal server error |
 | 502 | Provisioning service unavailable or returned an error |
+| 503 | Provisioning is temporarily disabled (kill switch active) |
 
 ## Agent interaction
 
@@ -836,7 +839,7 @@
 |-------|------|----------|-------------|
 | `action` | string | Yes | `set-credential` |
 | `key` | string | Yes | Credential key (for example, `anthropic`, `telegram`) |
 | `value` | string | No | Credential value. When omitted, the credential is marked as unconfigured. |
 
 ```json
 {