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.
- package/docs/ai-gateway/azure-ai.mdx +132 -0
- package/docs/ai-gateway/cookbooks/sdk-path-shim.mdx +457 -0
- package/docs/ai-gateway/integrations/ai-sdk.mdx +127 -1
- package/docs/ai-gateway/integrations/claude-code.mdx +82 -180
- package/docs/ai-gateway/integrations/claude-desktop.mdx +61 -99
- package/docs/ai-gateway/integrations/codex.mdx +63 -57
- package/docs/ai-gateway/vertex-ai.mdx +32 -0
- package/docs/articles/custom-domains.mdx +3 -2
- package/docs/articles/source-control.mdx +4 -3
- package/docs/articles/testing.mdx +5 -5
- package/docs/articles/upstream-iam-auth.mdx +2 -2
- package/docs/concepts/how-zuplo-works.mdx +2 -1
- package/docs/dev-portal/migration.mdx +2 -2
- package/docs/getting-started/dev-portal/index.mdx +2 -2
- package/docs/getting-started/gateway/add-api-key-auth/index.mdx +3 -0
- package/docs/getting-started/gateway/add-api-key-auth/local.mdx +3 -0
- package/docs/getting-started/gateway/add-rate-limiting/index.mdx +3 -0
- package/docs/getting-started/gateway/add-rate-limiting/local.mdx +3 -0
- package/docs/getting-started/gateway/agent.mdx +2 -1
- package/docs/getting-started/gateway/deploy-to-the-edge/index.mdx +3 -0
- package/docs/getting-started/gateway/deploy-to-the-edge/local.mdx +3 -0
- package/docs/getting-started/gateway/dynamic-rate-limiting/index.mdx +3 -0
- package/docs/getting-started/gateway/dynamic-rate-limiting/local.mdx +3 -0
- package/docs/getting-started/gateway/setup-a-basic-gateway/index.mdx +4 -1
- package/docs/getting-started/gateway/setup-a-basic-gateway/local.mdx +4 -1
- package/docs/getting-started/mcp-gateway/local.mdx +31 -9
- package/docs/getting-started/mcp-gateway/portal.mdx +8 -7
- package/docs/getting-started/mcp-server/local.mdx +2 -2
- package/docs/getting-started/migrate/index.mdx +2 -2
- package/docs/mcp-gateway/connect-clients/claude-desktop.mdx +21 -19
- package/docs/mcp-gateway/connect-clients/overview.mdx +2 -1
- package/docs/policies/ai-gateway-auth-v2-inbound/doc.md +10 -0
- package/package.json +5 -5
|
@@ -2,156 +2,118 @@
|
|
|
2
2
|
title: Claude Desktop
|
|
3
3
|
sidebar_label: Claude Desktop
|
|
4
4
|
description:
|
|
5
|
-
|
|
6
|
-
|
|
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)
|
|
10
|
-
|
|
11
|
-
|
|
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
|
-
##
|
|
16
|
+
## Prerequisites
|
|
18
17
|
|
|
19
18
|
<Stepper>
|
|
20
19
|
|
|
21
|
-
1. Create
|
|
22
|
-
Anthropic
|
|
20
|
+
1. Create an Anthropic [provider](../managing-providers.mdx) in the AI Gateway.
|
|
23
21
|
|
|
24
|
-
2. [
|
|
22
|
+
2. [Create a team](../managing-teams.mdx).
|
|
25
23
|
|
|
26
|
-
3. Create
|
|
27
|
-
|
|
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**
|
|
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
|
-
|
|
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.
|
|
61
|
-
|
|
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.
|
|
40
|
+
3. Under **Connection**, set **Inference provider** to **Gateway**.
|
|
66
41
|
|
|
67
|
-
4.
|
|
68
|
-
|
|
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.
|
|
76
|
-
|
|
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
|
|
79
|
-
relaunches
|
|
53
|
+
7. Click **Apply locally**. Claude Desktop saves the configuration and
|
|
54
|
+
relaunches.
|
|
80
55
|
|
|
81
56
|
</Stepper>
|
|
82
57
|
|
|
83
|
-
|
|
58
|
+
### Rules
|
|
84
59
|
|
|
85
|
-
|
|
86
|
-
|
|
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
|
-
:::
|
|
69
|
+
:::warning{title="Replace the provider name"}
|
|
91
70
|
|
|
92
|
-
The
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
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
|
-
|
|
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
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
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.
|
|
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
|
|
118
|
-
|
|
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
|
|
130
|
-
|
|
131
|
-
### Verify the configuration
|
|
97
|
+
policy controls which models the app can use.
|
|
132
98
|
|
|
133
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
112
|
+
## Deploy to a fleet
|
|
148
113
|
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
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
|
|
10
|
-
|
|
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 [
|
|
22
|
-
provider you want to use with Codex
|
|
14
|
+
1. Create a [provider](../managing-providers.mdx) in the AI Gateway.
|
|
23
15
|
|
|
24
|
-
2. [
|
|
16
|
+
2. [Create a team](../managing-teams.mdx).
|
|
25
17
|
|
|
26
|
-
3. Create
|
|
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**
|
|
20
|
+
4. Copy the **API URL** and **API Key** from the app page.
|
|
30
21
|
|
|
31
22
|
</Stepper>
|
|
32
23
|
|
|
33
|
-
## Configure Codex
|
|
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
|
-
|
|
42
|
-
selected in the Codex configuration and work with any OpenAI compatible
|
|
43
|
-
models
|
|
26
|
+
:::warning{title="Replace the provider name"}
|
|
44
27
|
|
|
45
|
-
|
|
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
|
-
|
|
33
|
+
:::
|
|
48
34
|
|
|
49
|
-
|
|
50
|
-
`~/.codex
|
|
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
|
-
|
|
57
|
-
|
|
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
|
-
|
|
63
|
-
|
|
49
|
+
- `base_url` is the app's API URL with `/v1` appended.
|
|
50
|
+
- `model` is `providerName/model`.
|
|
64
51
|
|
|
65
|
-
|
|
52
|
+
Set the API key in your environment:
|
|
66
53
|
|
|
67
|
-
|
|
68
|
-
|
|
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
|
-
|
|
78
|
-
|
|
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
|
-
|
|
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
|
|
89
|
-
|
|
90
|
-
|
|
86
|
+
policy controls which models the app can use.
|
|
87
|
+
|
|
88
|
+
## Verify
|
|
91
89
|
|
|
92
90
|
```bash
|
|
93
|
-
codex
|
|
91
|
+
codex exec "Reply with the single word OK"
|
|
94
92
|
```
|
|
95
93
|
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
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
|
-
|
|
26
|
-
|
|
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
|
-
|
|
69
|
-
main environment. Push to `feature-auth` and get a
|
|
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
|
-
|
|
144
|
-
preview environment
|
|
145
|
-
|
|
146
|
-
|
|
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
|
-
|
|
23
|
-
|
|
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
|
|
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
|
-
|
|
129
|
-
|
|
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
|
|
12
|
-
|
|
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.
|
|
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" />
|