zuplo 7.8.10 → 7.8.12

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/docs/ai-gateway/integrations/codex.mdx +73 -13
  2. package/docs/policies/mcp-token-exchange-inbound/doc.md +9 -7
  3. package/package.json +5 -5
package/docs/ai-gateway/integrations/codex.mdx CHANGED
@@ -7,13 +7,23 @@ description: Route Codex CLI requests through a Zuplo AI Gateway app.
7
7
  [Codex](https://developers.openai.com/codex) is OpenAI's coding agent for the
8
8
  terminal. This guide routes its requests through the Zuplo AI Gateway.
9
9
 
10
+ Two approaches:
11
+
12
+ - **Use a provider key.** The gateway calls OpenAI with the API key saved on
13
+ your provider. OpenAI bills that key's account.
14
+ - **Use your ChatGPT subscription.** Codex stays signed in with `codex login`.
15
+ The gateway forwards that login to OpenAI and meters usage against your app.
16
+ Your ChatGPT plan pays for the tokens.
17
+
10
18
  ## Prerequisites
11
19
 
12
20
  <Stepper>
13
21
 
14
- 1. Create a [provider](../managing-providers.mdx) in the AI Gateway.
22
+ 1. Create an OpenAI [provider](../managing-providers.mdx) in the AI Gateway.
15
23
 
16
- 2. [Create a team](../managing-teams.mdx).
24
+ 2. [Create a team](../managing-teams.mdx). For the subscription approach,
25
+ [configure its API Key Authentication policy](#configure-the-api-key-authentication-policy)
26
+ now.
17
27
 
18
28
  3. [Create an app](../managing-apps.mdx) for Codex and assign it to the team.
19
29
 
@@ -33,7 +43,14 @@ serves. Check [your provider's page](../managing-providers.mdx) in the Portal.
33
43
  :::
34
44
 
35
45
  Codex reads configuration from `~/.codex/config.toml`. Create this file (and the
36
- `~/.codex` directory if needed) if it does not exist. Add the following:
46
+ `~/.codex` directory if needed) if it does not exist. Add the block for your
47
+ approach, then set the API key in your environment and restart Codex:
48
+
49
+ ```bash
50
+ export ZUPLO_AI_GATEWAY_API_KEY="<your-app-api-key>"
51
+ ```
52
+
53
+ ### Use a provider key
37
54
 
38
55
  ```toml
39
56
  model_provider = "zuplo"
@@ -49,13 +66,50 @@ wire_api = "responses"
49
66
  - `base_url` is the app's API URL with `/v1` appended.
50
67
  - `model` is `providerName/model`.
51
68
 
52
- Set the API key in your environment:
69
+ ### Use your ChatGPT subscription
53
70
 
54
- ```bash
55
- export ZUPLO_AI_GATEWAY_API_KEY="<your-app-api-key>"
71
+ ```toml
72
+ model_provider = "zuplo"
73
+ model = "openai/gpt-5.6-sol"
74
+
75
+ [model_providers.zuplo]
76
+ name = "Zuplo AI Gateway"
77
+ base_url = "https://my-gateway-main-2e18f50.zuplo.app/config_fe0a04972d2848e0a94ae4b8bcd1497e/v1"
78
+ wire_api = "responses"
79
+ requires_openai_auth = true
80
+ env_http_headers = { "zp-gateway-api-key" = "ZUPLO_AI_GATEWAY_API_KEY" }
56
81
  ```
57
82
 
58
- Restart Codex. All requests now go through the gateway.
83
+ - `requires_openai_auth = true` makes Codex send your ChatGPT login in the
84
+ `Authorization` header. Do not set `env_key`.
85
+ - `env_http_headers` sends the app's API key in the `zp-gateway-api-key` header,
86
+ which is where the passthrough policy reads it.
87
+ - `model` must be a model your ChatGPT plan can use in Codex, with your provider
88
+ name as the prefix.
89
+
90
+ Run `codex login` if you are not signed in. The gateway never sends your ChatGPT
91
+ login anywhere except OpenAI, and never sends your app key to OpenAI.
92
+
93
+ #### Configure the API Key Authentication policy
94
+
95
+ On the team's [policy template](../policy-templates.mdx), or on the app's
96
+ **Policies** tab, edit **API Key Authentication** in the **JSON** editor:
97
+
98
+ ```json
99
+ {
100
+ "credentialPassthrough": true,
101
+ "authHeader": "zp-gateway-api-key",
102
+ "authScheme": ""
103
+ }
104
+ ```
105
+
106
+ `authScheme` must be the empty string, not left blank. A blank field keeps the
107
+ `Bearer` default and every request fails with
108
+ `401 Invalid Authorization Scheme`.
109
+
110
+ The provider still needs an API key saved. Passthrough requests never use it;
111
+ [Fallback Model](../../policies/ai-gateway-fallback-model-v2-inbound.mdx)
112
+ targets do. A placeholder value works if nothing else uses it.
59
113
 
60
114
  ### Rules
61
115
 
@@ -66,6 +120,8 @@ Restart Codex. All requests now go through the gateway.
66
120
  `/v1/chat/completions`, and `wire_api = "chat"` fails to load.
67
121
  - Put this configuration in the user-level file. Codex ignores `model_provider`
68
122
  and `model_providers` in a project-level `.codex/config.toml`.
123
+ - Do not use `openai_base_url` to point Codex at the gateway. That keeps Codex's
124
+ built-in transport, which the gateway does not support.
69
125
 
70
126
  ## Switch models
71
127
 
@@ -96,9 +152,13 @@ usage in the Zuplo Portal.
96
152
 
97
153
  ## Troubleshooting
98
154
 
99
- | Error | Fix |
100
- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------- |
101
- | `400` `The request body model must use "providerName/model"` | Add the provider prefix to `model`. Do not use the `/model` picker. |
102
- | `ERROR: Missing environment variable: ZUPLO_AI_GATEWAY_API_KEY` | Export the variable in the shell that runs Codex. |
103
- | `401` `Authorization Failed` | The API key is wrong. Copy it from the app's **API Key** tab. |
104
- | Errors mention `api.openai.com` or `not supported when using Codex with a ChatGPT account` | Codex is not using your provider. Set `model_provider = "zuplo"`. |
155
+ | Error | Fix |
156
+ | ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------- |
157
+ | `400` `The request body model must use "providerName/model"` | Add the provider prefix to `model`. Do not use the `/model` picker. |
158
+ | `ERROR: Missing environment variable: ZUPLO_AI_GATEWAY_API_KEY` | Export the variable in the shell that runs Codex. |
159
+ | `401` `Authorization Failed` | The API key is wrong. Copy it from the app's **API Key** tab. |
160
+ | `401` `Header configured by options.authHeader is missing` | Subscription approach: add the `env_http_headers` line and export `ZUPLO_AI_GATEWAY_API_KEY`. |
161
+ | `401` `Invalid Authorization Scheme` | Set `authScheme` to the empty string in the policy JSON. |
162
+ | `401` `rejected the credential this app passed through from the caller` `(HTTP 401)` | Your ChatGPT login expired or is invalid. Run `codex login` again. |
163
+ | `401` `Missing scopes: api.responses.write` | The app is not in passthrough mode. Configure the API Key Authentication policy as above. |
164
+ | Errors mention `api.openai.com` or `not supported when using Codex with a ChatGPT account` | Codex is not using your provider. Set `model_provider = "zuplo"`. |
package/docs/policies/mcp-token-exchange-inbound/doc.md CHANGED
@@ -284,15 +284,17 @@ Gateway authorization errors fall into three buckets:
284
284
  | Upstream service response | The upstream server returned its own error page or OAuth error. | Treat the upstream response as the source of truth and fix the upstream URL, allowlist, account region, or provider configuration. |
285
285
 
286
286
  For browser-based OAuth failures, the gateway error page shows a user-friendly
287
- message and visible developer details. Developer details include the gateway
288
- error code, request id, and the underlying reason so screenshots are useful in
289
- support tickets.
287
+ message, numbered next steps, and a reference block with the gateway error code,
288
+ request id, and time for the user to share. A technical-details section below it
289
+ lists the suggested fix, the underlying reason, the stage, and the upstream
290
+ request fields so screenshots are useful in support tickets.
290
291
 
291
292
  If the upstream returns an HTML error response, such as an edge firewall
292
- `403 Access Denied` page, the gateway displays that upstream HTML response on
293
- the error page instead of replacing it with only a generic gateway message. This
294
- usually means the upstream URL is not publicly reachable from the gateway or the
295
- provider has not allowed this client/network/account to access the MCP endpoint.
293
+ `403 Access Denied` page, the gateway keeps that upstream HTML response on the
294
+ error page behind a "Show the provider's response" disclosure instead of
295
+ replacing it with only a generic gateway message. This usually means the
296
+ upstream URL is not publicly reachable from the gateway or the provider has not
297
+ allowed this client/network/account to access the MCP endpoint.
296
298
 
297
299
  Common examples:
298
300
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "zuplo",
3
- "version": "7.8.10",
3
+ "version": "7.8.12",
4
4
  "type": "module",
5
5
  "description": "The official Zuplo CLI for local development and platform management",
6
6
  "homepage": "https://zuplo.com/docs/cli/overview",
@@ -32,9 +32,9 @@
32
32
  "zuplo": "zuplo.js"
33
33
  },
34
34
  "dependencies": {
35
- "@zuplo/cli": "7.8.10",
36
- "@zuplo/core": "7.8.10",
37
- "@zuplo/runtime": "7.8.10",
38
- "@zuplo/test": "7.8.10"
35
+ "@zuplo/cli": "7.8.12",
36
+ "@zuplo/core": "7.8.12",
37
+ "@zuplo/runtime": "7.8.12",
38
+ "@zuplo/test": "7.8.12"
39
39
  }
40
40
  }