zuplo 7.8.8 → 7.8.10

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 (33) hide show
  1. package/docs/ai-gateway/azure-ai.mdx +132 -0
  2. package/docs/ai-gateway/cookbooks/sdk-path-shim.mdx +457 -0
  3. package/docs/ai-gateway/integrations/ai-sdk.mdx +127 -1
  4. package/docs/ai-gateway/integrations/claude-code.mdx +82 -180
  5. package/docs/ai-gateway/integrations/claude-desktop.mdx +61 -99
  6. package/docs/ai-gateway/integrations/codex.mdx +63 -57
  7. package/docs/ai-gateway/vertex-ai.mdx +32 -0
  8. package/docs/articles/custom-domains.mdx +3 -2
  9. package/docs/articles/source-control.mdx +4 -3
  10. package/docs/articles/testing.mdx +5 -5
  11. package/docs/articles/upstream-iam-auth.mdx +2 -2
  12. package/docs/concepts/how-zuplo-works.mdx +2 -1
  13. package/docs/dev-portal/migration.mdx +2 -2
  14. package/docs/getting-started/dev-portal/index.mdx +2 -2
  15. package/docs/getting-started/gateway/add-api-key-auth/index.mdx +3 -0
  16. package/docs/getting-started/gateway/add-api-key-auth/local.mdx +3 -0
  17. package/docs/getting-started/gateway/add-rate-limiting/index.mdx +3 -0
  18. package/docs/getting-started/gateway/add-rate-limiting/local.mdx +3 -0
  19. package/docs/getting-started/gateway/agent.mdx +2 -1
  20. package/docs/getting-started/gateway/deploy-to-the-edge/index.mdx +3 -0
  21. package/docs/getting-started/gateway/deploy-to-the-edge/local.mdx +3 -0
  22. package/docs/getting-started/gateway/dynamic-rate-limiting/index.mdx +3 -0
  23. package/docs/getting-started/gateway/dynamic-rate-limiting/local.mdx +3 -0
  24. package/docs/getting-started/gateway/setup-a-basic-gateway/index.mdx +4 -1
  25. package/docs/getting-started/gateway/setup-a-basic-gateway/local.mdx +4 -1
  26. package/docs/getting-started/mcp-gateway/local.mdx +31 -9
  27. package/docs/getting-started/mcp-gateway/portal.mdx +8 -7
  28. package/docs/getting-started/mcp-server/local.mdx +2 -2
  29. package/docs/getting-started/migrate/index.mdx +2 -2
  30. package/docs/mcp-gateway/connect-clients/claude-desktop.mdx +21 -19
  31. package/docs/mcp-gateway/connect-clients/overview.mdx +2 -1
  32. package/docs/policies/ai-gateway-auth-v2-inbound/doc.md +10 -0
  33. package/package.json +5 -5
@@ -2,156 +2,118 @@
2
2
  title: Claude Desktop
3
3
  sidebar_label: Claude Desktop
4
4
  description:
5
- Point Claude Desktop at an AI Gateway app so every Chat, Cowork, and Code
6
- session is authenticated, metered, and routed by the gateway.
5
+ Route Claude Desktop's Chat, Cowork, and Code sessions through a Zuplo AI
6
+ Gateway app.
7
7
  ---
8
8
 
9
- [Claude Desktop](https://claude.com/download) can use the Zuplo AI Gateway as
10
- its inference provider, so the gateway authenticates, meters, and routes every
11
- Chat, Cowork, and Code session started from the desktop app.
9
+ Route [Claude Desktop](https://claude.com/download) through the Zuplo AI
10
+ Gateway. The gateway authenticates, meters, and routes every Chat, Cowork, and
11
+ Code session started from the app.
12
12
 
13
- This page covers routing Claude Desktop's model requests through the AI Gateway.
14
13
  To give Claude Desktop tools from a Zuplo MCP route instead, see
15
14
  [Connect Claude Desktop and Claude.ai](../../mcp-gateway/connect-clients/claude-desktop.mdx).
16
15
 
17
- ## Claude Desktop Setup
16
+ ## Prerequisites
18
17
 
19
18
  <Stepper>
20
19
 
21
- 1. Create a [new provider](../managing-providers.mdx) in the AI Gateway for
22
- Anthropic
20
+ 1. Create an Anthropic [provider](../managing-providers.mdx) in the AI Gateway.
23
21
 
24
- 2. [Set up a new team](../managing-teams.mdx)
22
+ 2. [Create a team](../managing-teams.mdx).
25
23
 
26
- 3. Create a [new app](../managing-apps.mdx) to use with Claude Desktop and
27
- assign it to the team you created
24
+ 3. [Create an app](../managing-apps.mdx) for Claude Desktop and assign it to the
25
+ team.
28
26
 
29
- 4. Copy the **API URL** and **API Key** shown at the top of the app page
30
-
31
- 5. Enter the API URL, API key, and model list in Claude Desktop's third-party
32
- inference settings
27
+ 4. Copy the **API URL** and **API Key** from the app page.
33
28
 
34
29
  </Stepper>
35
30
 
36
- ### Before copying: replace the provider name
37
-
38
- :::warning
39
-
40
- The examples below assume your provider is named `anthropic`. Replace that
41
- prefix with the name of **your** provider before copying the configuration. For
42
- example, a provider named `my-anthropic` routes `my-anthropic/claude-sonnet-5`,
43
- while a Bedrock provider named `bedrock` routes
44
- `bedrock/anthropic.claude-sonnet-5`. The model part must be an id that provider
45
- understands.
46
-
47
- :::
48
-
49
- The gateway routes every request using `providerName/model`. The provider prefix
50
- picks which of your providers handles the request — a gateway can contain
51
- several providers that serve Anthropic models.
52
-
53
- ### Configure third-party inference
54
-
55
- Configure Claude Desktop's inference provider in its in-app configuration
56
- window, available on macOS and Windows:
31
+ ## Configure Claude Desktop
57
32
 
58
33
  <Stepper>
59
34
 
60
- 1. From the menu bar (macOS) or the application menu (Windows), select **Help →
61
- Troubleshooting → Enable Developer Mode**.
35
+ 1. Select **Help → Troubleshooting → Enable Developer Mode** from the menu bar
36
+ (macOS) or the application menu (Windows).
62
37
 
63
38
  2. Open **Developer → Configure Third-Party Inference**.
64
39
 
65
- 3. In the **Connection** section, set **Inference provider** to **Gateway**.
40
+ 3. Under **Connection**, set **Inference provider** to **Gateway**.
66
41
 
67
- 4. In the **Gateway credentials** card, set **Gateway base URL** to the app's
68
- API URL, for example
42
+ 4. Under **Gateway credentials**, set **Gateway base URL** to the app's API URL,
43
+ for example
69
44
  `https://my-gateway-main-2e18f50.zuplo.app/config_fe0a04972d2848e0a94ae4b8bcd1497e`,
70
45
  and **Gateway API key** to the app's API key.
71
46
 
72
47
  5. Leave **Credential kind** set to **Static API key** and **Gateway auth
73
48
  scheme** set to **Bearer**.
74
49
 
75
- 6. In the **Models** section, add the models the app may use to the **Model
76
- list**. See [Add models to the Model list](#add-models-to-the-model-list).
50
+ 6. Under **Models**, add each model the app may use. See
51
+ [Add models](#add-models).
77
52
 
78
- 7. Click **Apply locally**. Claude Desktop writes the configuration and
79
- relaunches into it.
53
+ 7. Click **Apply locally**. Claude Desktop saves the configuration and
54
+ relaunches.
80
55
 
81
56
  </Stepper>
82
57
 
83
- :::note
58
+ ### Rules
84
59
 
85
- Claude Desktop appends `/v1/messages` to the base URL itself, so **Gateway base
86
- URL** is the app's URL _without_ the `/v1` suffix.
60
+ - **Gateway base URL** is the app's API URL _without_ `/v1`. Claude Desktop
61
+ appends `/v1/messages`.
62
+ - **Gateway auth scheme** stays **Bearer**. The gateway reads the API key from
63
+ the `Authorization: Bearer` header.
64
+ - **Credential kind** stays **Static API key**. AI Gateway apps authenticate
65
+ with API keys, not identity-provider tokens.
87
66
 
88
- :::
67
+ ## Add models
89
68
 
90
- :::caution{title="Keep the auth scheme set to Bearer"}
69
+ :::warning{title="Replace the provider name"}
91
70
 
92
- The gateway reads the API key from the `Authorization: Bearer` header, so keep
93
- **Gateway auth scheme** set to **Bearer**. Likewise, keep **Credential kind**
94
- set to **Static API key** — AI Gateway apps authenticate with their own API
95
- keys, not identity-provider tokens.
71
+ The examples assume your provider is named `anthropic`. Replace that prefix with
72
+ the name of **your** provider before entering any model. A provider named
73
+ `my-anthropic` routes `my-anthropic/claude-sonnet-5`; a Bedrock provider named
74
+ `bedrock` routes `bedrock/anthropic.claude-sonnet-5`. The model part must be an
75
+ ID that provider serves. Check [your provider's page](../managing-providers.mdx)
76
+ in the Portal.
96
77
 
97
78
  :::
98
79
 
99
- ### Add models to the Model list
100
-
101
- The **Model list** in the **Models** section overrides the model list Claude
102
- Desktop discovers on its own. Click **Add** once per model the app may use, and
103
- fill in each entry:
80
+ The **Model list** replaces the models Claude Desktop discovers on its own.
81
+ Click **Add** once per model:
104
82
 
105
83
  - **Model ID** — the full `providerName/model` reference, for example
106
- `anthropic/claude-sonnet-5`. A bare id such as `claude-sonnet-5` fails to
107
- route through the gateway.
108
- - **Display name** — the name shown in the model picker, for example
109
- `Claude Sonnet 5`. Leave it blank and Claude Desktop formats a name from the
110
- id.
111
- - **Offer 1M-context variant** — leave this off unless your provider's
112
- deployment accepts 1M-token context for the model.
84
+ `anthropic/claude-sonnet-5`. A bare ID fails with a `400`.
85
+ - **Display name** — the name in the model picker. Leave it blank and Claude
86
+ Desktop formats one from the ID.
87
+ - **Offer 1M-context variant** — off, unless your provider accepts 1M-token
88
+ context for the model.
113
89
  - **Tier alias** — the Claude tier (Opus, Sonnet, Haiku, or Fable) this model
114
- stands in for. Setting it pins what the bare alias (for example `opus`)
115
- resolves to, so tier names route to your prefixed model reference.
90
+ stands in for. The bare alias, for example `opus`, then resolves to it.
116
91
 
117
- The first entry is the default selection in the model picker. Include a
118
- Haiku-tier model — Claude Desktop runs background and sub-agent tasks on a
119
- small, fast model.
120
-
121
- The model ids in these examples reflect what was current when this page was
122
- written, and ids differ across providers — a Bedrock provider serves different
123
- ids than Anthropic directly, and availability can vary by region. Check
124
- [your provider's page](../managing-providers.mdx) in the portal for the models
125
- it currently serves, and use those ids.
92
+ The first entry is the picker default. Include a Haiku-tier model: Claude
93
+ Desktop runs background and sub-agent tasks on a small, fast model.
126
94
 
127
95
  The app's
128
96
  [Model Filtering](../../policies/ai-gateway-model-filtering-v2-inbound.mdx)
129
- policy controls which models the app may use.
130
-
131
- ### Verify the configuration
97
+ policy controls which models the app can use.
132
98
 
133
- After Claude Desktop relaunches, send a message in a Chat conversation and start
134
- a Cowork session. Both requests route through the gateway and count against the
135
- [app](../managing-apps.mdx) in the Zuplo Portal, as do Code sessions started
136
- from the desktop app. Terminal Claude Code sessions outside the desktop app use
137
- a separate configuration — see [Claude Code](./claude-code.mdx).
99
+ ## Verify
138
100
 
139
- :::caution{title='HTTP 400: model must use "providerName/model"'}
101
+ Send a message in Chat and start a Cowork session. Both appear in the app's
102
+ usage in the Zuplo Portal, as do Code sessions started from the desktop app.
103
+ Terminal Claude Code sessions use their own configuration. See
104
+ [Claude Code](./claude-code.mdx).
140
105
 
141
- If a request fails with `The request body model must use "providerName/model"`,
142
- the selected model reference is missing its provider prefix. Give every entry in
143
- the model list a full `providerName/model` reference.
106
+ ## Troubleshooting
144
107
 
145
- :::
108
+ | Error | Fix |
109
+ | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------- |
110
+ | `400` `The request body model must use "providerName/model"` | A model list entry has no provider prefix. Give every entry a full `providerName/model` ID. |
146
111
 
147
- ### Deploy to a fleet
112
+ ## Deploy to a fleet
148
113
 
149
- To roll the configuration out to many devices, use the configuration window's
150
- **Export** menu instead of **Apply locally**. It generates a `.mobileconfig`
151
- profile for macOS MDM tools such as Jamf, a `.reg` policy file for Intune or
152
- Group Policy, and related deployment artifacts. Managed configuration takes
153
- precedence over local settings, so users can't point the app at a different
154
- endpoint. For the deployment workflow and the full configuration key reference,
155
- see Anthropic's
114
+ Use the configuration window's **Export** menu instead of **Apply locally**. It
115
+ produces a `.mobileconfig` profile for macOS MDM tools such as Jamf, a `.reg`
116
+ policy file for Intune or Group Policy, and related artifacts. Managed
117
+ configuration overrides local settings. See Anthropic's
156
118
  [Deploy Claude Desktop with an LLM gateway](https://claude.com/docs/third-party/claude-desktop/gateway)
157
119
  and [Deploy with MDM](https://claude.com/docs/third-party/claude-desktop/mdm).
@@ -1,98 +1,104 @@
1
1
  ---
2
2
  title: Codex
3
3
  sidebar_label: Codex
4
- description:
5
- Configure the Codex CLI to send its requests through an AI Gateway app, either
6
- by rerouting the built-in OpenAI provider or by adding a Zuplo provider.
4
+ description: Route Codex CLI requests through a Zuplo AI Gateway app.
7
5
  ---
8
6
 
9
- [Codex](https://developers.openai.com/codex) is a coding agent developed by
10
- OpenAI that you can run locally from your terminal and that can read, modify,
11
- and run code on your machine, in the chosen directory. It’s open-source, and
12
- built in Rust for speed and efficiency.
7
+ [Codex](https://developers.openai.com/codex) is OpenAI's coding agent for the
8
+ terminal. This guide routes its requests through the Zuplo AI Gateway.
13
9
 
14
10
  ## Prerequisites
15
11
 
16
- In order to use the AI Gateway with Codex you will need to complete these steps
17
- first:
18
-
19
12
  <Stepper>
20
13
 
21
- 1. Create a [new provider](../managing-providers.mdx) in the AI Gateway for the
22
- provider you want to use with Codex
14
+ 1. Create a [provider](../managing-providers.mdx) in the AI Gateway.
23
15
 
24
- 2. [Set up a new team](../managing-teams.mdx)
16
+ 2. [Create a team](../managing-teams.mdx).
25
17
 
26
- 3. Create a [new app](../managing-apps.mdx) to use specifically with Codex and
27
- assign it to the team you created
18
+ 3. [Create an app](../managing-apps.mdx) for Codex and assign it to the team.
28
19
 
29
- 4. Copy the **API URL** and **API Key** shown at the top of the app page
20
+ 4. Copy the **API URL** and **API Key** from the app page.
30
21
 
31
22
  </Stepper>
32
23
 
33
- ## Configure Codex CLI
34
-
35
- There are two approaches you can take to using Codex with Zuplo's AI Gateway.
36
-
37
- 1. **Route OpenAI through AI Gateway** - This would configure your OpenAI
38
- provider in Codex to route requests through the AI Gateway rather than
39
- directly to OpenAI
24
+ ## Configure Codex
40
25
 
41
- 2. **Create a Zuplo specific provider** - Use Zuplo as a provider that be
42
- selected in the Codex configuration and work with any OpenAI compatible
43
- models
26
+ :::warning{title="Replace the provider name"}
44
27
 
45
- Configuration steps for both options are below:
28
+ The examples assume your provider is named `openai`. Replace that prefix with
29
+ the name of **your** provider before copying anything. A provider named
30
+ `my-openai` routes `my-openai/gpt-5`. The model part must be an ID that provider
31
+ serves. Check [your provider's page](../managing-providers.mdx) in the Portal.
46
32
 
47
- ### Route OpenAI through AI Gateway
33
+ :::
48
34
 
49
- Open the [Codex configuration](https://developers.openai.com/codex/local-config)
50
- `~/.codex/config.toml` and modify the `model_providers.openai-chat-completions`
51
- entry so that the `base_url` points to your app's API URL with `/v1` appended,
52
- and set your `env_key` to the API Key of the app you created to use with Codex.
53
- The app page in the Zuplo Portal shows the API URL, which ends in the app's ID.
35
+ 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:
54
37
 
55
38
  ```toml
56
- [model_providers.openai-chat-completions]
57
- name = "OpenAI using Chat Completions"
39
+ model_provider = "zuplo"
40
+ model = "openai/gpt-5"
41
+
42
+ [model_providers.zuplo]
43
+ name = "Zuplo AI Gateway"
58
44
  base_url = "https://my-gateway-main-2e18f50.zuplo.app/config_fe0a04972d2848e0a94ae4b8bcd1497e/v1"
59
45
  env_key = "ZUPLO_AI_GATEWAY_API_KEY"
46
+ wire_api = "responses"
60
47
  ```
61
48
 
62
- Save the file and reload Codex. Your OpenAI requests will now be routed through
63
- the Zuplo AI Gateway.
49
+ - `base_url` is the app's API URL with `/v1` appended.
50
+ - `model` is `providerName/model`.
64
51
 
65
- ### Zuplo AI Gateway provider
52
+ Set the API key in your environment:
66
53
 
67
- To add a specific provider for the AI Gateway you can add an additional entry to
68
- the Codex `config.toml` file.
69
-
70
- ```toml
71
- [model_providers.zuplo]
72
- name = "Zuplo AI Gateway"
73
- base_url = "https://my-gateway-main-2e18f50.zuplo.app/config_fe0a04972d2848e0a94ae4b8bcd1497e/v1"
74
- env_key = "ZUPLO_AI_GATEWAY_API_KEY"
54
+ ```bash
55
+ export ZUPLO_AI_GATEWAY_API_KEY="<your-app-api-key>"
75
56
  ```
76
57
 
77
- Save the file and reload Codex. Your Zuplo AI Gateway provider will now be
78
- available and you can switch Codex over to use it at any time by running:
58
+ Restart Codex. All requests now go through the gateway.
59
+
60
+ ### Rules
61
+
62
+ - `model_provider = "zuplo"` is required. Without it, Codex uses its built-in
63
+ `openai` provider and bypasses the gateway.
64
+ - `wire_api` must be `responses`. Codex speaks only the Responses API; it
65
+ [removed](https://github.com/openai/codex/discussions/7782) support for
66
+ `/v1/chat/completions`, and `wire_api = "chat"` fails to load.
67
+ - Put this configuration in the user-level file. Codex ignores `model_provider`
68
+ and `model_providers` in a project-level `.codex/config.toml`.
69
+
70
+ ## Switch models
71
+
72
+ Set `model` in `config.toml`, or pass it on the command line:
79
73
 
80
74
  ```bash
81
- codex --config model_provider="zuplo"
75
+ codex --config model_provider="zuplo" --model "openai/gpt-5.6-sol"
82
76
  ```
83
77
 
84
- ### Choosing a model
78
+ Do not use the `/model` picker. It sends model names without the provider
79
+ prefix, and the gateway rejects them with a `400`.
80
+
81
+ Codex warns that it has no metadata for a prefixed model name. Requests still
82
+ succeed.
85
83
 
86
84
  The app's
87
85
  [Model Filtering](../../policies/ai-gateway-model-filtering-v2-inbound.mdx)
88
- policy controls which models the app may use. Codex names the model as
89
- `providerName/model`, where `providerName` is the provider name configured in
90
- your gateway:
86
+ policy controls which models the app can use.
87
+
88
+ ## Verify
91
89
 
92
90
  ```bash
93
- codex --config model_provider="zuplo" --model "openai/gpt-5"
91
+ codex exec "Reply with the single word OK"
94
92
  ```
95
93
 
96
- A request with no model, or a model without that prefix, gets a `400`. Adding
97
- [Model Filtering](../../policies/ai-gateway-model-filtering-v2-inbound.mdx) with
98
- an allow list also supplies a default, letting requests omit the model.
94
+ The session header shows `provider: zuplo`. The request appears in the app's
95
+ usage in the Zuplo Portal.
96
+
97
+ ## Troubleshooting
98
+
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"`. |
@@ -358,6 +358,12 @@ const response = await client.chat.completions.create({
358
358
  Streaming works the same way—set `stream: true` and read the
359
359
  `chat.completion.chunk` events.
360
360
 
361
+ For the Vercel AI SDK, use `@ai-sdk/openai-compatible` for Gemini and Model
362
+ Garden models and `@ai-sdk/anthropic` for Claude—see the
363
+ [Vertex AI section](./integrations/ai-sdk.mdx#vertex-ai) of the AI SDK page. The
364
+ `@ai-sdk/google-vertex` provider doesn't work; see
365
+ [Troubleshooting](#troubleshooting).
366
+
361
367
  ### Embeddings
362
368
 
363
369
  Embeddings use the same client and the same `/v1/embeddings` endpoint as any
@@ -474,6 +480,32 @@ doesn't serve the model is the separate `400` described above.
474
480
  require the project to turn on data sharing for the `anthropic` publisher. The
475
481
  error names the `setPublisherModelConfig` setting to change.
476
482
 
483
+ **A request fails when you use `@ai-sdk/google-vertex`.** The provider posts to
484
+ Vertex's own publisher paths—`{model}:generateContent` for Gemini, and
485
+ `{model}:rawPredict` on its `/anthropic` entry—which the gateway doesn't serve,
486
+ so both return a `404`. Use `@ai-sdk/openai-compatible` for Gemini and Model
487
+ Garden models and `@ai-sdk/anthropic` for Claude—see the
488
+ [AI SDK Vertex section](./integrations/ai-sdk.mdx#vertex-ai). For its
489
+ `/anthropic` (Claude) entry specifically, the
490
+ [SDK path shim](./cookbooks/sdk-path-shim.mdx) can repoint
491
+ `@ai-sdk/google-vertex/anthropic` onto `/v1/messages`; the Gemini entry can't be
492
+ repointed that way.
493
+
494
+ **A request fails when you use `@anthropic-ai/vertex-sdk`.** The
495
+ `AnthropicVertex` client rewrites the request onto Vertex's
496
+ `publishers/anthropic/models/{model}:rawPredict` path, which the gateway doesn't
497
+ serve. Use the plain `Anthropic` client from `@anthropic-ai/sdk` with
498
+ `authToken`—see
499
+ [Call Claude models on the Messages API](#call-claude-models-on-the-messages-api).
500
+ To keep using `AnthropicVertex` instead, install the
501
+ [SDK path shim](./cookbooks/sdk-path-shim.mdx), which rewrites that publisher
502
+ path onto `/v1/messages`.
503
+
504
+ **A request fails when you use `@google/genai`.** With `vertexai: true` the
505
+ client posts to Gemini's native `{model}:generateContent` path, and it also
506
+ misreads a two-slash model reference as `publisher/model`. Use an OpenAI client
507
+ on `/v1/chat/completions`—see [Call the models](#call-the-models).
508
+
477
509
  ## Next steps
478
510
 
479
511
  - [AI Providers](./providers.mdx)—the capability matrix across every supported
@@ -22,8 +22,9 @@ Zuplo supports two types of custom domains that can be configured separately:
22
22
  `cname.zuplodocs.com`. Learn more about the Developer Portal in the
23
23
  [Developer Portal documentation](/docs/dev-portal/overview).
24
24
 
25
- Both types of custom domains can be managed from the same Custom Domains section
26
- in your project settings and follow a similar configuration process.
25
+ Manage both types of custom domains in
26
+ [**Account Settings → Custom Domains**](https://portal.zuplo.com/+/account/settings/custom-domains).
27
+ They follow a similar configuration process.
27
28
 
28
29
  :::note
29
30
 
@@ -65,9 +65,10 @@ If your code lives elsewhere but you want to use a specific CI/CD system:
65
65
 
66
66
  ## How Branch-Based Deployments Work
67
67
 
68
- Every Git branch maps to a Zuplo environment. Push to `main` and deploy to your
69
- main environment. Push to `feature-auth` and get a `feature-auth` environment
70
- automatically.
68
+ With the GitHub integration, every Git branch maps to a Zuplo environment. Push
69
+ to `main` and deploy to your main environment. Push to `feature-auth` and get a
70
+ `feature-auth` environment automatically. For other providers, configure your
71
+ CI/CD pipeline to deploy each branch.
71
72
 
72
73
  This enables powerful workflows like PR preview environments where reviewers can
73
74
  test changes against a live API before merging.
@@ -140,11 +140,11 @@ and the same file supplies fixture values to `zuplo test`. See
140
140
 
141
141
  ## Test before merge
142
142
 
143
- Every branch pushed to your connected source control provider deploys as a
144
- preview environment: a full Zuplo deployment on the same edge network as
145
- production, at its own URL. Running your suite there is the highest-fidelity
146
- check available before a change merges, and it needs no shared staging
147
- environment.
143
+ With the GitHub integration, pushing a feature branch automatically creates a
144
+ preview environment at its own URL. For GitLab, Bitbucket, or Azure DevOps,
145
+ configure a [CI/CD pipeline](./custom-ci-cd.mdx) to deploy the branch. Running
146
+ your suite against a preview deployment lets you test changes before merging
147
+ without a shared staging environment.
148
148
 
149
149
  - [Testing preview environments](./testing-preview-environments.mdx) — getting
150
150
  the URL into your tests, per-environment services and secrets, and what to
@@ -19,8 +19,8 @@ identity provider you control. For the alternatives, see
19
19
 
20
20
  ## Federated identity or stored credentials
21
21
 
22
- Every provider offers two paths, and the choice matters more than which cloud
23
- you're on.
22
+ Zuplo offers federated identity and stored-credential policies. The available
23
+ options depend on your cloud provider, as shown in the policy table below.
24
24
 
25
25
  **Federated identity** is the stronger option. Zuplo presents a short-lived,
26
26
  audience-bound OIDC token that proves which gateway is calling, and your cloud
@@ -87,7 +87,8 @@ workflow is:
87
87
 
88
88
  1. **Develop** locally or in the Zuplo Portal
89
89
  2. **Push** to your Git repository (GitHub, GitLab, Bitbucket, or Azure DevOps)
90
- 3. **Deploy** automatically - Zuplo builds and deploys your gateway globally
90
+ 3. **Deploy** automatically with the GitHub integration, or configure a CI/CD
91
+ pipeline to deploy from GitLab, Bitbucket, or Azure DevOps
91
92
 
92
93
  Deployments complete in seconds. Each Git branch gets its own isolated
93
94
  environment with its own URL, making it easy to test changes before merging to
@@ -125,8 +125,8 @@ process, continue with the manual migration steps below.
125
125
 
126
126
  :::caution
127
127
 
128
- Currently, this migration must be done locally. It cannot be done in the
129
- Zuplo Portal.
128
+ Follow these manual migration steps locally. To migrate in the Zuplo Portal,
129
+ use the [built-in migration tool](#migrate-in-the-portal).
130
130
 
131
131
  :::
132
132
 
@@ -8,8 +8,8 @@ centered: false
8
8
  toc: false
9
9
  title: Getting Started with Developer Portal
10
10
  description:
11
- Publish docs and self-serve API keys with Zudoku with Zuplo, in the Portal,
12
- locally with the CLI, or with an AI agent.
11
+ Publish interactive API docs and let consumers manage their API keys through a
12
+ developer portal built in the Portal, locally, or with an AI agent.
13
13
  ---
14
14
 
15
15
  <WizardSteps build="dev-portal" />
@@ -1,5 +1,6 @@
1
1
  ---
2
2
  category: API Management
3
+ disablePager: true
3
4
  showLastModified: false
4
5
  suggestEdit: false
5
6
  title: Add API key authentication - Portal
@@ -166,3 +167,5 @@ Let's get started.
166
167
  [our developer portal auth docs](/docs/dev-portal/zudoku/configuration/authentication).
167
168
 
168
169
  </Stepper>
170
+
171
+ <TutorialPager build="gateway" method="portal" step="add-api-key-auth" />
@@ -1,5 +1,6 @@
1
1
  ---
2
2
  category: API Management
3
+ disablePager: true
3
4
  showLastModified: false
4
5
  suggestEdit: false
5
6
  title: Add API key authentication - Editor
@@ -154,3 +155,5 @@ Let's get started.
154
155
  :::
155
156
 
156
157
  </Stepper>
158
+
159
+ <TutorialPager build="gateway" method="local" step="add-api-key-auth" />
@@ -1,5 +1,6 @@
1
1
  ---
2
2
  category: API Management
3
+ disablePager: true
3
4
  showLastModified: false
4
5
  suggestEdit: false
5
6
  title: Add rate limiting - Portal
@@ -81,3 +82,5 @@ limiter.
81
82
  echo API.
82
83
 
83
84
  </Stepper>
85
+
86
+ <TutorialPager build="gateway" method="portal" step="add-rate-limiting" />
@@ -1,5 +1,6 @@
1
1
  ---
2
2
  category: API Management
3
+ disablePager: true
3
4
  showLastModified: false
4
5
  suggestEdit: false
5
6
  title: Add rate limiting - Editor
@@ -100,3 +101,5 @@ full power of the world's best rate limiter.
100
101
  your API.
101
102
 
102
103
  </Stepper>
104
+
105
+ <TutorialPager build="gateway" method="local" step="add-rate-limiting" />
@@ -1,5 +1,6 @@
1
1
  ---
2
2
  category: API Management
3
+ disablePager: true
3
4
  showLastModified: false
4
5
  suggestEdit: false
5
6
  title: Getting Started with API Gateway - Agent
@@ -84,7 +85,7 @@ from inside your project directory.
84
85
  2. Add the rate-limiting inbound policy (rateLimitBy: ip, 2 requests / 1 minute) to every route.
85
86
  3. Add the api-key-inbound policy to every route, ordered before rate limiting.
86
87
  4. Make rate limiting dynamic: create modules/rate-limit.ts exporting rateLimit() that returns 1000 req/min for user.data.customerType === "premium", 5 for "free", 30 otherwise, and switch the policy to rateLimitBy: "function".
87
- 5. Run npm run dev and verify with curl that GET /todos returns 401 without a key. I will create the free and premium keys in the Portal afterward; leave key-based tests for me.
88
+ 5. Use the already-running dev server to verify with curl that GET /todos returns 401 without a key. I will create the free and premium keys in the Portal afterward; leave key-based tests for me.
88
89
 
89
90
  Explain each config change in one line and stop before pushing to git.
90
91
  ```
@@ -1,5 +1,6 @@
1
1
  ---
2
2
  category: API Management
3
+ disablePager: true
3
4
  showLastModified: false
4
5
  suggestEdit: false
5
6
  title: Deploy to the edge - Portal
@@ -229,3 +230,5 @@ when running commits, pulls or try to open a pull request.
229
230
  - If the GitHub repository has been renamed or moved to a different
230
231
  organization, try disconnecting and reconnecting to it. You can do this by
231
232
  going to your Zuplo project's settings > Source Control section
233
+
234
+ <TutorialPager build="gateway" method="portal" step="deploy-to-the-edge" />
@@ -1,5 +1,6 @@
1
1
  ---
2
2
  category: API Management
3
+ disablePager: true
3
4
  showLastModified: false
4
5
  suggestEdit: false
5
6
  title: Deploy to the edge - Editor
@@ -132,3 +133,5 @@ Zuplo project in the Portal. The local files alone cannot receive a deployment.
132
133
  :::
133
134
 
134
135
  </Stepper>
136
+
137
+ <TutorialPager build="gateway" method="local" step="deploy-to-the-edge" />
@@ -1,5 +1,6 @@
1
1
  ---
2
2
  category: API Management
3
+ disablePager: true
3
4
  showLastModified: false
4
5
  suggestEdit: false
5
6
  title: Dynamic rate limiting - Portal
@@ -175,3 +176,5 @@ less than an hour.
175
176
  questions answered
176
177
  - Start generating revenue from your new API with our
177
178
  [Monetization tutorial](../../../articles/monetization/index.mdx)
179
+
180
+ <TutorialPager build="gateway" method="portal" step="dynamic-rate-limiting" />