diff --git a/docs.json b/docs.json index eb60fe2d1..75e13798b 100644 --- a/docs.json +++ b/docs.json @@ -343,6 +343,27 @@ "product/admin/enterprise-managed-authorization/audit", "product/admin/enterprise-managed-authorization/support-in-your-app" ] + }, + { + "group": "Edge Gateway", + "tag": "NEW", + "pages": [ + "product/admin/edge-gateway-overview", + "product/admin/edge-gateway-quickstart", + "product/admin/edge-gateway-setup", + "product/admin/edge-gateway-inference-routing", + "product/admin/edge-gateway-access", + { + "group": "Connect tools", + "pages": [ + "product/admin/claude-code-edge-gateway-multipass", + "product/admin/edge-gateway-codex", + "product/admin/connect-edge-gateway-multipass", + "product/admin/edge-gateway-connect", + "product/admin/inference-api-keys" + ] + } + ] } ] }, diff --git a/images/product/assets/edge-add-dialog.png b/images/product/assets/edge-add-dialog.png new file mode 100644 index 000000000..b49c35123 Binary files /dev/null and b/images/product/assets/edge-add-dialog.png differ diff --git a/images/product/assets/edge-add-models-key.png b/images/product/assets/edge-add-models-key.png new file mode 100644 index 000000000..8007b3a39 Binary files /dev/null and b/images/product/assets/edge-add-models-key.png differ diff --git a/images/product/assets/edge-bearer-tokens.png b/images/product/assets/edge-bearer-tokens.png new file mode 100644 index 000000000..29fce0b2f Binary files /dev/null and b/images/product/assets/edge-bearer-tokens.png differ diff --git a/images/product/assets/edge-connection-details.png b/images/product/assets/edge-connection-details.png new file mode 100644 index 000000000..34d9b8d99 Binary files /dev/null and b/images/product/assets/edge-connection-details.png differ diff --git a/images/product/assets/edge-grant-access.png b/images/product/assets/edge-grant-access.png new file mode 100644 index 000000000..fba0b38e1 Binary files /dev/null and b/images/product/assets/edge-grant-access.png differ diff --git a/images/product/assets/edge-grants.png b/images/product/assets/edge-grants.png new file mode 100644 index 000000000..958bd4b4d Binary files /dev/null and b/images/product/assets/edge-grants.png differ diff --git a/images/product/assets/edge-how-to-connect-codex.png b/images/product/assets/edge-how-to-connect-codex.png new file mode 100644 index 000000000..619483ef4 Binary files /dev/null and b/images/product/assets/edge-how-to-connect-codex.png differ diff --git a/images/product/assets/edge-how-to-connect.png b/images/product/assets/edge-how-to-connect.png new file mode 100644 index 000000000..cfccc2730 Binary files /dev/null and b/images/product/assets/edge-how-to-connect.png differ diff --git a/images/product/assets/edge-inference-routes.png b/images/product/assets/edge-inference-routes.png new file mode 100644 index 000000000..125c54783 Binary files /dev/null and b/images/product/assets/edge-inference-routes.png differ diff --git a/images/product/assets/edge-new-route.png b/images/product/assets/edge-new-route.png new file mode 100644 index 000000000..bfeabff13 Binary files /dev/null and b/images/product/assets/edge-new-route.png differ diff --git a/images/product/assets/edge-setup-checklist.png b/images/product/assets/edge-setup-checklist.png new file mode 100644 index 000000000..5aab16463 Binary files /dev/null and b/images/product/assets/edge-setup-checklist.png differ diff --git a/images/product/assets/edge-turn-on.png b/images/product/assets/edge-turn-on.png new file mode 100644 index 000000000..a200bb050 Binary files /dev/null and b/images/product/assets/edge-turn-on.png differ diff --git a/images/product/assets/inference-api-key-create.png b/images/product/assets/inference-api-key-create.png new file mode 100644 index 000000000..6896e364b Binary files /dev/null and b/images/product/assets/inference-api-key-create.png differ diff --git a/images/product/assets/multipass-edge-gateway-settings.png b/images/product/assets/multipass-edge-gateway-settings.png new file mode 100644 index 000000000..e1dea1a75 Binary files /dev/null and b/images/product/assets/multipass-edge-gateway-settings.png differ diff --git a/product/admin/claude-code-edge-gateway-multipass.mdx b/product/admin/claude-code-edge-gateway-multipass.mdx new file mode 100644 index 000000000..6b3d180ce --- /dev/null +++ b/product/admin/claude-code-edge-gateway-multipass.mdx @@ -0,0 +1,146 @@ +--- +title: Use Claude Code with Edge Gateway +description: Run Claude Code against your organization's Edge Gateway with short-lived inference tokens that C1 Multipass issues from your device session — no Anthropic API key. +og:title: Use Claude Code with Edge Gateway - C1 docs +og:description: Run Claude Code against your organization's Edge Gateway with short-lived inference tokens that C1 Multipass issues from your device session — no Anthropic API key. +sidebarTitle: Claude Code +--- + +{/* Editor Refresh: 2026-10-28 */} + + +**Early access.** This feature is in early access, which means it's undergoing ongoing testing and development while we gather feedback, validate functionality, and improve outputs. Contact the C1 Support team if you'd like to try it out or share feedback. + + +Run Claude Code against your organization's Edge Gateway without an Anthropic API key. Claude Code calls the C1 Multipass command line tool whenever it needs a credential, and C1 Multipass returns a short-lived token that only works for inference on your Edge Gateway. Requests are attributed to you, and your organization's Edge Gateway policy applies to them. + +## How the Claude Code key helper works + +Claude Code supports an `apiKeyHelper` setting: a command it runs to get an API key. Point it at `c1-multipass inference helper`, and each call does the following: + +1. The C1 Multipass service uses this device's registered session to ask C1 for an inference grant on your Edge Gateway. +2. Edge Gateway issues a bearer token limited to listing models and running inference, valid for at most five minutes, with no refresh token. +3. The command prints the token, and Claude Code sends it to your Edge Gateway's inference URL. + +Claude Code calls Edge Gateway directly over HTTPS. It doesn't use the local inference or egress endpoints from [Route other tools through C1 Multipass](/product/admin/connect-edge-gateway-multipass), so you don't need to turn on routing or load credentials into your shell. + +## Before you begin with Claude Code and Edge Gateway + +Confirm the following before you start: + +| Requirement | Who provides it | +| :--- | :--- | +| macOS with C1 Multipass and its command line tool (`c1-multipass`) installed, signed in to your C1 tenant, the device registered, and the app unlocked. See [Set up Multipass](/product/admin/connect-edge-gateway-multipass#set-up-multipass). | You | +| Access to an Edge Gateway that serves Claude models. The key helper works whether **Allow long-lived API keys** is on or off. See [Set up an Edge for inference](/product/admin/edge-gateway-setup) and [Grant access to an Edge](/product/admin/edge-gateway-access). | Your C1 admin | +| Make sure **Cross-App Access** is on under **AI** > **Cross-App Access** so Multipass can get Edge tokens for people. The Edge's **Overview** warns if it's off. If the setting isn't available, contact the C1 Support team. See [Enable enterprise-managed authorization](/product/admin/enterprise-managed-authorization/enable). | Your C1 admin | +| Your Edge Gateway's inference endpoint, for example `https://-inference.edge.`. See [Find the Edge's connection values](/product/admin/edge-gateway-connect#find-the-edges-connection-details). | Your C1 admin | +| Claude Code installed | You | + +The helper workflow on this page requires macOS. The desktop app is also available for Windows, but the inference-helper CLI and **Command line tool** installation aren't available there. For enrolled Linux hosts, see the [fleet routing setup](/product/admin/connect-edge-gateway-multipass#turn-on-edge-gateway-routing). + +## Check that your Edge Gateway issues inference tokens + +Before configuring Claude Code, confirm C1 Multipass can get a token. This command prints only the token's prefix, not the token itself: + +```bash +c1-multipass inference helper --dial-only | cut -c1-14 +``` + +The output starts with `tb_inf_at_v1.`. If the command prints an error instead, see [Troubleshoot Claude Code with Edge Gateway](#troubleshoot-claude-code-with-edge-gateway). + +**Optional.** List the models available to you, and confirm the Claude models you plan to use are there: + +```bash +curl -s --noproxy '*' https:///v1/models \ + -H "Authorization: Bearer $(c1-multipass inference helper --dial-only)" \ + | grep -o '"id":"[^"]*"' +``` + +## Configure Claude Code to use Edge Gateway + +Copy the settings from **Connect your tools** > **Claude Code** into `~/.claude/settings.json`. Merge them with your existing settings; don't overwrite the file. + + + The Connect your tools card with Set up Multipass collapsed, Claude Code selected, and the beginning of the settings.json configuration. + + + + +Open `~/.claude/settings.json`, creating the file if it doesn't exist. + + +Merge the following settings. Replace the inference host and the app and Edge IDs with the values from your Edge's **Connection details**. Use the inference origin without a trailing slash or `/v1` suffix for both `--edge-url` and `ANTHROPIC_BASE_URL`. Replace `` with a Claude route from your Edge's model list. + +```json +{ + "apiKeyHelper": "c1-multipass inference helper --edge-url https:// --inference-resource https:///api/v1/apps//edges/ --dial-only", + "env": { + "ANTHROPIC_BASE_URL": "https://", + "ANTHROPIC_MODEL": "", + "CLAUDE_CODE_API_KEY_HELPER_TTL_MS": "60000" + } +} +``` + +The helper command pins the credential to this Edge's inference resource. If `c1-multipass` isn't on Claude Code's `PATH`, replace it with the installed command's full path, such as `/Users//.local/bin/c1-multipass`. The 60000-millisecond helper TTL makes Claude Code request a fresh credential every 60 seconds. + + +Run a one-time prompt with other Anthropic credentials removed: + +```bash +env -u ANTHROPIC_API_KEY -u ANTHROPIC_AUTH_TOKEN -u HTTPS_PROXY \ + claude -p "Reply with exactly: edge ok" +``` + +`env -u` removes the two named Anthropic credentials and the uppercase `HTTPS_PROXY` variable for this command. It doesn't remove other proxy variables or system proxy settings; check those separately if the request still uses a proxy. If Claude Code asks you to approve the API key helper, approve it. + + + +A reply of `edge ok` confirms that this prompt completed through the configured Edge. Use the same `env -u` prefix for interactive launches while other Anthropic credentials remain in your shell. Choose a model with `--model` or `/model` from your Edge's Claude routes. + + +To opt in per session instead of changing your default configuration, save these settings in `~/.config/c1-edge/claude-settings.json`, preserving any existing file. Add `--settings ~/.config/c1-edge/claude-settings.json` to the `claude` command. Keep the same explicit Edge URL and resource in the helper command. + + +## Keep the inference token private + +The key helper prints a real bearer token. Anyone holding it can run inference as you on your Edge Gateway until it expires, within five minutes. + +- Don't print the token to your terminal, save it to a file, or paste it anywhere. The commands on this page pass it straight to Claude Code or curl. +- Stopping Edge Gateway routing or locking C1 Multipass doesn't revoke a token already issued. It expires on its own. +- The token only works for inference. It can't be used for egress or other C1 APIs. + +## Troubleshoot Claude Code with Edge Gateway + +Most problems show up when you run the key helper directly: + +```bash +c1-multipass inference helper --dial-only | cut -c1-14 +``` + +| Symptom | What to do | +| :--- | :--- | +| `EDGE_SELECTION_REQUIRED` | You have access to more than one Edge Gateway. Select one in C1 Multipass, or use the explicit Edge URL and inference resource in [Configure Claude Code](#configure-claude-code-to-use-edge-gateway). | +| `NO_USABLE_EDGE` | You don't have inference access on any Edge Gateway. Ask your C1 admin for access. | +| `EDGE_GRANT_DENIED` at **C1 Edge grant** | Ask your C1 admin to check the Edge capability entitlements and the `token_exchange` event in the system log. | +| `EDGE_GRANT_DENIED` at **Edge inference redemption** | C1 issued the grant, but the Edge refused redemption. Ask your admin to check Edge policy and runtime compatibility. The long-lived API key setting isn't a helper prerequisite. | +| The helper reports that the C1 Multipass service isn't signed in, isn't running, or refused the connection | Open and unlock C1 Multipass, and confirm this device is registered. On macOS, open C1 Multipass from **/Applications**. | +| The helper fails, but local routing works | Confirm that the helper uses the same Edge and inference resource as routing. **Allow long-lived API keys** doesn't control helper tokens. Share the helper's error with your C1 admin. | +| Claude Code reports an authentication error | Run the test in [Configure Claude Code to use Edge Gateway](#configure-claude-code-to-use-edge-gateway) with `env -u`. If it succeeds there, another credential in your environment or `~/.claude/settings.json` is overriding the key helper. | +| Claude Code reports that a model isn't available | Pick a model from your Edge Gateway's model list. | + +## Frequently asked questions about Claude Code with Edge Gateway + + + + No. Edge Gateway authenticates the request with the token from C1 Multipass and calls the model provider with your organization's credentials. + + + + Claude Code adds query parameters to its requests, such as `/v1/messages?beta=true`, and the local inference endpoint rejects request URLs with a query string. The key helper connects Claude Code to Edge Gateway directly. + + + + Yes, for any tool that runs a command to get an API key and sends it as a bearer token. Point the tool's base URL at your Edge Gateway inference URL. + + diff --git a/product/admin/connect-edge-gateway-multipass.mdx b/product/admin/connect-edge-gateway-multipass.mdx new file mode 100644 index 000000000..9ddcb95df --- /dev/null +++ b/product/admin/connect-edge-gateway-multipass.mdx @@ -0,0 +1,418 @@ +--- +title: Route other tools through C1 Multipass +description: Send your AI tools' model calls and outbound HTTPS traffic through your organization's Edge Gateway, attributed to you, using the C1 Multipass device session you already have — no separate API keys. +og:title: Route other tools through C1 Multipass - C1 docs +og:description: Send your AI tools' model calls and outbound HTTPS traffic through your organization's Edge Gateway, attributed to you, using the C1 Multipass device session you already have — no separate API keys. +sidebarTitle: Other tools (local routing) +--- + +{/* Editor Refresh: 2026-10-28 */} + + +**Early access.** This feature is in early access, which means it's undergoing ongoing testing and development while we gather feedback, validate functionality, and improve outputs. Contact the C1 Support team if you'd like to try it out or share feedback. + + +Point compatible tools at C1 Multipass local endpoints to send their configured model calls and HTTPS proxy traffic through your organization's Edge Gateway. Multipass uses your registered device session, so you don't manage provider API keys. Traffic that a tool sends elsewhere doesn't use these endpoints. + +For [Claude Code](/product/admin/claude-code-edge-gateway-multipass) and [Codex](/product/admin/edge-gateway-codex), use their dedicated guides. Their desktop configurations use short-lived key helpers and connect directly to the Edge; they don't need local routing enabled. Enrolled servers use the fleet/local-endpoint path below. + +## How C1 Multipass connects to Edge Gateway + +The C1 Multipass service runs on your device and holds its registered device session. When Edge Gateway routing is on, the service opens two endpoints on the device's loopback interface: + +| Endpoint | Default address | Use it for | +| :--- | :--- | :--- | +| Inference | `http://127.0.0.1:18080/v1` | An OpenAI-compatible API. Supports `GET /v1/models`, `POST /v1/chat/completions`, `POST /v1/responses`, and `POST /v1/messages`. | +| Egress | `http://127.0.0.1:18081` | An HTTPS proxy (`HTTPS_PROXY`) for tools that make their own outbound calls. | + +Both endpoints require a local key, because any process on the device can reach a loopback port. The C1 Multipass command line tool loads the key into your shell's environment. The service never logs the key. + +Your C1 admin decides which models and destinations you can reach. Edge Gateway enforces that policy on every request. + +## Edge Gateway setup at a glance + +Set up Multipass before configuring a client. For tools that need local endpoints, continue with routing: + +1. [Set up Multipass](#set-up-multipass) and its command line tool. +2. [Turn on Edge Gateway routing](#turn-on-edge-gateway-routing) to start the local endpoints for the Edge's enabled capabilities. +3. [Load the endpoint credentials into your shell](#load-the-endpoint-credentials-into-your-shell): the endpoint addresses and the local key. +4. [List models and run inference](#list-models-and-run-inference) through the inference endpoint. +5. [Send outbound HTTPS traffic through Edge Gateway](#send-outbound-https-traffic-through-edge-gateway) after your tools trust the Edge Gateway CA. + +## Supported platforms for Edge Gateway routing + +How you turn on routing depends on the platform: + +| Platform | How routing runs | Command line tool | +| :--- | :--- | :--- | +| macOS (Apple silicon) | The C1 Multipass desktop app starts routing while it's unlocked. | `c1-multipass` | +| Linux (x86_64 and arm64) | The C1 Multipass headless service (`multipass-runtime`) starts routing when it holds a device session. | `c1-multipass-fleet` | +| Windows | Not supported yet. | — | + +The rest of this page uses `c1-multipass headless edge` for commands. On a Linux service host, run the same subcommands as `c1-multipass-fleet edge`. + +## Before you begin with Edge Gateway routing + +Confirm the following before you start. Egress is the most common gap: it needs your device to trust your organization's Edge Gateway certificate authority (CA). + +| Requirement | Who provides it | +| :--- | :--- | +| C1 Multipass installed, connected to your C1 tenant, and the device registered. See [Set up Multipass](#set-up-multipass). | You, or your IT team for managed Linux hosts | +| Access to at least one Edge Gateway. See [Grant access to an Edge](/product/admin/edge-gateway-access). | Your C1 admin | +| Make sure **Cross-App Access** is on under **AI** > **Cross-App Access** so Multipass can get Edge tokens for people. The Edge's **Overview** warns if it's off. If the setting isn't available, contact the C1 Support team. See [Enable enterprise-managed authorization](/product/admin/enterprise-managed-authorization/enable). | Your C1 admin | +| For egress: your organization's Edge Gateway CA certificate and its SHA-256 fingerprint | Your C1 admin, or your device management (MDM) profile | + +## Set up Multipass + +Install and sign in to Multipass before using a desktop key helper or local routing. The public [C1 Multipass downloads](https://dist.conductorone.com/ConductorOne/multipass-desktop) page offers macOS (Apple silicon) and Windows (x64). The inference-helper CLI and the **Command line tool** installation described below require macOS; they aren't available on Windows. Local Edge routing isn't supported on Windows yet. + +On macOS, complete these steps: + + + +Download the desktop app, move it to **/Applications**, and open it from there rather than from the disk image or Downloads folder. + + +Sign in to your C1 tenant and complete device registration. Keep the app unlocked while setting up a key helper or starting routing. + + +Open **Settings** > **General**. Next to **Command line tool**, click **Install**, then add `~/.local/bin` to your `PATH`. C1 Multipass doesn't edit your shell configuration. + +```bash +echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc +``` + + + +The `c1-multipass` command now uses your registered device session. For Claude Code or desktop Codex, return to the client guide; you don't need to turn on local routing. + +Linux service hosts use an enrolled Multipass runtime and `c1-multipass-fleet`, not the desktop app. Follow the **Linux service** instructions under [Turn on Edge Gateway routing](#turn-on-edge-gateway-routing). + +## Turn on Edge Gateway routing + +Select your platform. + + + + +Turn on routing from the C1 Multipass app. The app must be unlocked to start routing. After it starts, routing keeps running when the app locks. + + +Open C1 Multipass from **/Applications**, not from the downloaded disk image. macOS runs apps launched from a disk image or the Downloads folder from a temporary location, and the C1 Multipass service refuses instructions from an app at an unexpected path. If you opened it from the disk image, quit the app, eject the disk image, and open it again from **/Applications**. + + + + +In C1 Multipass, open **Settings** > **General**. + + +Turn on **Route AI traffic through Edge**. + + +If the app shows **Open Login Items**, click it and allow **C1 Multipass** in System Settings. This lets the C1 Multipass service run in the background. + + +**Optional.** If you have access to more than one Edge Gateway, choose one from the **Edge** list. + + +If the status shows **Start**, click it. + + + +The status line reads **Running at http://127.0.0.1:18080/v1**, and the **Edge** row shows the Edge Gateway in use. + + + C1 Multipass Settings > General, showing the Command line tool row with an Install button, and Route AI traffic through Edge turned on with the status Running at http://127.0.0.1:18080/v1 and the selected Edge Gateway. + + + + + +On Linux, the headless C1 Multipass service runs routing. With the default start mode, routing starts as soon as the service holds a device session, with no desktop app involved. These steps assume the service is installed under systemd and its device is registered. + + + +Choose how the service finds its Edge Gateway, in `/etc/multipass-runtime/environment`. To let C1 report the Edge Gateways the device's user can use, turn on discovery: + +```bash +MULTIPASS_EDGE_DISCOVER=1 +``` + +To pin a specific Edge Gateway instead, set its audience and resources, which your C1 admin provides: + +```bash +MULTIPASS_EDGE_AUDIENCE=https:// +MULTIPASS_EDGE_INFERENCE_RESOURCE= +MULTIPASS_EDGE_EGRESS_RESOURCE= +``` + + +Restart the service. + +```bash +sudo systemctl restart multipass-runtime +``` + + +**Optional.** If discovery finds more than one Edge Gateway, list them and select one. The service remembers the choice. + +```bash +c1-multipass-fleet edge list +c1-multipass-fleet edge select / +``` + + +**Optional.** To keep the same local key across service restarts, set `edge_local_key_path` in `/etc/multipass-runtime/config.toml` to an owner-only (`0600`) file containing at least 32 random URL-safe characters. + + + +The service serves both endpoints after its next device session is established. The user running the command line tool must be allowed to connect to the service in `config.toml`; ask your IT team if commands report that the service refused the connection. + + + + +Check the routing status from a terminal: + +```bash +c1-multipass headless edge status +``` + +On an enrolled Linux host, use `c1-multipass-fleet edge status`. Use the same `c1-multipass-fleet edge` prefix for the `env`, `start`, and `stop` commands below instead of `c1-multipass headless edge`. + +The `running` field reports a local listener. The `ready` field reports whether every configured capability has unexpired cached grants; an inference-only Edge doesn't need an egress grant. Neither field proves that a model request can reach the provider. + +## Load the endpoint credentials into your shell + +Your tools need two things to use Edge Gateway: the endpoint addresses and the local key. The command line tool prints both as shell `export` lines, and only to the user who runs it. Use `eval` so the local key goes straight into the environment instead of your screen or shell history. + +```bash +eval "$(c1-multipass headless edge env)" +``` + +This sets three variables in the current shell: + +| Variable | Value | +| :--- | :--- | +| `OPENAI_BASE_URL` | `http://127.0.0.1:18080/v1` | +| `OPENAI_API_KEY` | The local key | +| `HTTPS_PROXY` | `http://c1:@127.0.0.1:18081` | + +Tools you start from this shell now use Edge Gateway. Run the command again in each new shell. Unless the key is pinned, run it again after the C1 Multipass service restarts, because the key changes on restart. + +Check the health route for each capability you use. The health route doesn't need the local key. + +```bash +curl -s http://127.0.0.1:18080/_c1/health +curl -s http://127.0.0.1:18081/_c1/health +``` + +Both health routes report the same cached-grant readiness for the configured capabilities. An `{"ok":true}` response doesn't make a fresh remote request. If a route returns `{"ok":false,"reason":"..."}`, record the reason before changing configuration. Also run a model request to check provider credentials, model routing, and inference permission. + +## List models and run inference + +The inference endpoint accepts OpenAI-style requests, so any tool or SDK that reads `OPENAI_BASE_URL` and `OPENAI_API_KEY` works without code changes. Run these commands in a shell where you loaded the endpoint credentials. + +### List the models available to you + +Your C1 admin decides which models your Edge Gateway exposes. List them: + +```bash +curl -s "$OPENAI_BASE_URL/models" -H "Authorization: Bearer $OPENAI_API_KEY" +``` + +The response is an OpenAI-style list. Each entry's `id` is the model name to use in requests, and its `capabilities` show the request formats and features it supports: + +```json +{ + "object": "list", + "data": [ + { + "id": "", + "object": "model", + "capabilities": { "input_formats": ["openai_responses"], "streaming": true } + } + ] +} +``` + +To print only the model names: + +```bash +curl -s "$OPENAI_BASE_URL/models" -H "Authorization: Bearer $OPENAI_API_KEY" | jq -r '.data[].id' +``` + +### Run an inference request + +Send a request to a model from the list. This example uses the Responses API format: + +```bash +curl -s "$OPENAI_BASE_URL/responses" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{"model": "", "input": "Say hello", "store": false}' +``` + +For a model that lists the chat completions format, use `/chat/completions` instead: + +```bash +curl -s "$OPENAI_BASE_URL/chat/completions" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{"model": "", "messages": [{"role": "user", "content": "Say hello"}]}' +``` + +OpenAI SDKs pick up the same variables, so existing code runs through Edge Gateway unchanged: + +```python +from openai import OpenAI + +client = OpenAI() # reads OPENAI_BASE_URL and OPENAI_API_KEY +response = client.responses.create(model="", input="Say hello", store=False) +print(response.output_text) +``` + +Requests must use `Content-Type: application/json` and name exactly one model. The endpoint rejects request URLs that carry a query string. Each model's entry in the model list describes the request formats and options it supports. + + +Some clients add query parameters to every request. For example, Claude Code calls `/v1/messages?beta=true`, so don't point `ANTHROPIC_BASE_URL` at the local inference endpoint. To use Claude Code, see [Use Claude Code with Edge Gateway](/product/admin/claude-code-edge-gateway-multipass). + + +## Send outbound HTTPS traffic through Edge Gateway + +The egress endpoint is an HTTPS proxy. Edge Gateway inspects the traffic it carries, so it presents certificates issued by your organization's Edge Gateway CA. Your tools must trust that CA, or their requests fail with errors such as `unable to get local issuer certificate`. + +### Get the Edge Gateway CA certificate + +Your Edge Gateway publishes its CA certificate at a fixed path on your Edge Gateway host. Your C1 admin can give you the host name and the expected SHA-256 fingerprint. + + + +Download the CA certificate. `--noproxy '*'` keeps this request off the egress proxy. + +```bash +mkdir -p ~/.config/c1-edge +curl -fsS --noproxy '*' -o ~/.config/c1-edge/ca.pem \ + https:///.well-known/timebandit/ca.pem +``` + + +Print the certificate's fingerprint and compare it with the one your admin gave you. Don't use the certificate if they differ. + +```bash +openssl x509 -in ~/.config/c1-edge/ca.pem -noout -subject -fingerprint -sha256 +``` + + +Build a trust bundle that contains your system's root certificates and the Edge Gateway CA. Some destinations pass through Edge Gateway without inspection and present their own certificates, so tools need both. Use the system bundle path for your platform from the table below. + +```bash +cat ~/.config/c1-edge/ca.pem > ~/.config/c1-edge/bundle.pem +``` + +| Platform | System bundle | +| :--- | :--- | +| macOS | `/etc/ssl/cert.pem` | +| Debian, Ubuntu | `/etc/ssl/certs/ca-certificates.crt` | +| RHEL, Fedora, Amazon Linux | `/etc/pki/tls/certs/ca-bundle.crt` | + + + +`~/.config/c1-edge/bundle.pem` now holds the certificates your command line tools need. + +### Point your tools at the trust bundle + +Many command line tools and language runtimes don't read the operating system's trust store. Set each runtime's trust variable: + +| Runtime | Variable | Value | +| :--- | :--- | :--- | +| OpenSSL-based tools | `SSL_CERT_FILE` | `~/.config/c1-edge/bundle.pem` | +| curl | `CURL_CA_BUNDLE` | `~/.config/c1-edge/bundle.pem` | +| Python `requests` | `REQUESTS_CA_BUNDLE` | `~/.config/c1-edge/bundle.pem` | +| Node.js | `NODE_EXTRA_CA_CERTS` | `~/.config/c1-edge/ca.pem` | + +Then make a request through the proxy: + +```bash +curl -s --proxy "$HTTPS_PROXY" --noproxy '' \ + -o /dev/null -w '%{http_code}\n' https://api.github.com +``` + +A `200` response confirms this request succeeded through the configured proxy. It doesn't establish whether the destination used inspection or pass-through. A `403` response may indicate a destination policy denial; check the response and Edge activity. + +### Optional: Distribute the Edge Gateway CA to managed devices + +Admins can deploy the CA centrally instead of each user downloading it: + +- **macOS**: deploy the CA certificate as a trusted certificate profile through your MDM, such as Microsoft Intune or Jamf Pro. Only an MDM-delivered profile marks a root certificate as trusted without a user prompt. Browsers and apps that use the Keychain then trust Edge Gateway. +- **Linux**: install the CA into the system trust store with your configuration management tool. On Debian and Ubuntu, copy it to `/usr/local/share/ca-certificates/c1-edge.crt` and run `update-ca-certificates`. On RHEL and Fedora, copy it to `/etc/pki/ca-trust/source/anchors/` and run `update-ca-trust`. +- **Command line tools on any platform**: deploy a script that downloads the CA from the path above, checks its fingerprint, writes the trust bundle, and sets the variables from the previous section in users' shell profiles. + +## Optional: Turn Edge Gateway on and off per shell + +Add two shell functions so one command turns routing and trust on for the current shell, and another turns them off. Add them to your shell profile, such as `~/.zshrc` or `~/.bashrc`: + +```bash +# C1 Multipass Edge Gateway routing +edge-on() { + eval "$(c1-multipass headless edge env)" + export NO_PROXY="127.0.0.1,localhost" + export SSL_CERT_FILE="$HOME/.config/c1-edge/bundle.pem" + export CURL_CA_BUNDLE="$HOME/.config/c1-edge/bundle.pem" + export REQUESTS_CA_BUNDLE="$HOME/.config/c1-edge/bundle.pem" + export NODE_EXTRA_CA_CERTS="$HOME/.config/c1-edge/ca.pem" +} +edge-off() { + unset OPENAI_BASE_URL OPENAI_API_KEY HTTPS_PROXY NO_PROXY \ + SSL_CERT_FILE CURL_CA_BUNDLE REQUESTS_CA_BUNDLE NODE_EXTRA_CA_CERTS +} +``` + +In a new shell, `edge-on` routes that shell's tools through Edge Gateway, and `edge-off` returns it to direct connections. + +## When Edge Gateway routing stops + +Routing stops when: + +- You turn off **Route AI traffic through Edge** (macOS), or run `c1-multipass headless edge stop`. +- You sign out of C1 Multipass or reset the device. +- The C1 Multipass service restarts. On macOS, unlock the app to start routing again. On Linux, the service starts routing again when it re-establishes its device session. + +Routing keeps running when the macOS app locks. + +## Troubleshoot Edge Gateway routing + +The macOS app's status line and the `reason` field from `c1-multipass headless edge status` or a health route identify most problems. + +| Message or reason | What to do | +| :--- | :--- | +| The Multipass service doesn't allow this app to control the Edge proxy. | macOS opened the app from a temporary location. Quit it, eject the disk image, open C1 Multipass from **/Applications**, then turn **Route AI traffic through Edge** off and on. | +| The Multipass service isn't installed on this device, or isn't responding. | On macOS, click **Open Login Items** and allow C1 Multipass, or restart the app. On Linux, check `systemctl status multipass-runtime`. | +| The Multipass service isn't signed in yet. (`NO_DEVICE_SESSION`) | On macOS, unlock C1 Multipass. On Linux, confirm the service's device is registered. | +| The Multipass service has no Edge proxy configured. (`NOT_CONFIGURED`) | On Linux, set `MULTIPASS_EDGE_DISCOVER=1` or a pinned Edge Gateway in the service environment. | +| You don't have access to an Edge. (`NO_USABLE_EDGE`) | Confirm you're signed in to the intended C1 account, then ask your C1 admin to check the Edge's state and your model grants. | +| Choose which Edge to use. (`EDGE_SELECTION_REQUIRED`) | Pick an Edge Gateway in **Settings** > **General** (macOS), or run `c1-multipass-fleet edge select` (Linux). | +| Your organization denied Edge access for this device. (`EDGE_GRANT_DENIED`) | Ask your C1 admin to check your Edge Gateway access and this device's registration. | +| Not available on this platform. (`UNSUPPORTED_PLATFORM`) | Edge Gateway routing isn't supported on Windows yet. | +| `missing or wrong local key` | Run `eval "$(c1-multipass headless edge env)"` again. The key changed when the service restarted. | +| `unable to get local issuer certificate` | Your tool doesn't trust the Edge Gateway CA. See [Point your tools at the trust bundle](#point-your-tools-at-the-trust-bundle). | +| `unsupported inference route` | Check the request path and query string. For Claude Code, use the [key helper](/product/admin/claude-code-edge-gateway-multipass) instead of changing its local endpoint URL. | + +## Frequently asked questions about Edge Gateway routing + + + + No. C1 Multipass authenticates each request to Edge Gateway as you, using this device's session. The local key only protects the loopback endpoints on your device. + + + + Not without the local key. Loopback ports are reachable by every local user, so both endpoints reject requests without the key. Edge Gateway routing is intended for single-user devices; a shared host needs a separate setup per user. + + + + Starting routing requires an unlocked app. After that, the C1 Multipass service keeps serving so long-running tools don't fail when your screen locks. Turn off **Route AI traffic through Edge** or sign out to stop it. + + + + On Linux, set `MULTIPASS_EDGE_INFERENCE_LISTEN` and `MULTIPASS_EDGE_EGRESS_LISTEN` in the service environment to other loopback addresses. The macOS desktop app uses `127.0.0.1:18080` and `127.0.0.1:18081`. In scripts, read the addresses from `c1-multipass headless edge status` rather than hardcoding them. + + diff --git a/product/admin/edge-gateway-access.mdx b/product/admin/edge-gateway-access.mdx new file mode 100644 index 000000000..d4dc11839 --- /dev/null +++ b/product/admin/edge-gateway-access.mdx @@ -0,0 +1,97 @@ +--- +title: Grant access to an Edge +description: Decide who can list and call the models an Edge Gateway serves, by granting its List models and Call models entitlements to people or service principals. +og:title: Grant access to an Edge - C1 docs +og:description: Decide who can list and call the models an Edge Gateway serves, by granting its List models and Call models entitlements to people or service principals. +sidebarTitle: Grant access +--- + +{/* Editor Refresh: 2026-10-28 */} + + +**Early access.** This feature is in early access, which means it's undergoing ongoing testing and development while we gather feedback, validate functionality, and improve outputs. Contact the C1 Support team if you'd like to try it out or share feedback. + + +Give people or service principals access to an Edge Gateway from its **Grants** tab. For inference, the tab groups **List models** and **Call models** into one **Inference** capability. + +## Edge Gateway entitlements + +Each Edge has two entitlements on its parent application: + +| Entitlement | Scope | Lets the caller | +| :--- | :--- | :--- | +| **List models** | `inference.models.read` | See which models the Edge serves (`GET /v1/models`) | +| **Call models** | `inference.invoke` | Send requests to the Edge's models | + +The scopes are separate: **Call models** doesn't include **List models**, and many tools list models before calling one. Adding a member to the **Inference** capability grants both entitlements together. Workload callers need both. + +## Grant access to people or service principals + +Add members directly from the Edge's **Grants** tab. You don't need to create an access profile for a direct grant. + + + The Grants tab with an Inference capability containing List models and Call models, no access profile yet, and a Members section with an Add member button. + + + + +Open the Edge: **Apps** > *your app* > **Edge** > *your Edge*. + + +Click the **Grants** tab. + + +Under **Members**, select the **Inference** tab. If the Edge also serves egress, make sure you're adding members to the intended capability. + + +Click **Add member**. The **Grant access: Inference** dialog opens. + + +In **Person or service principal**, select the identities to grant access to. + + +Click **Grant access**. + + + + + The Grant access: Inference dialog with a Person or service principal picker and Cancel and Grant access buttons. + + +The identities appear in **Members**. The **Access via** column shows why they have access, such as **Added by owner**, **Rule**, **Access profile**, or **Request**. Use the filters above the table to inspect each source. + + +You can add people or service principals, but membership doesn't change the Edge's caller configuration. **People who sign in** accepts authorized human callers; **A workload** requires the configured service principal and workload federation trust. Check **Who can call** in the **Overview** checklist, expanding **Show checklist** if it's collapsed. See [Choose who can call the Edge](/product/admin/edge-gateway-setup#choose-who-can-call-the-edge). + + +## Remove a direct grant + +Remove an owner-added assignment from the **Members** table: + +1. Open the member's **...** (more actions) menu. +2. Select **Remove from capability**. +3. Review the confirmation and click **Remove**. + +This removes the owner-added assignment from the capability's entitlements. A member with another source of access can retain access through that source. For rule-based access, use **Open in Edit access** to change the rule. For access-profile membership, remove the membership in the access profile. For request-based access, use **Open request** to manage the request. **Remove from capability** is unavailable when there is no owner-added assignment to remove. + +## Optional: Configure automatic membership and requests + +Use an access profile when you want automatic membership, requestable access, or policies for the **Inference** capability. A direct **Add member** grant doesn't require one. + +1. In the capability summary at the top of **Grants**, click **Create access profile** in the **Inference** row if no profile exists. C1 creates a profile containing both inference entitlements. +2. Click **Edit access** in that row. +3. Under **Automatic membership**, keep **Nobody** selected for no automatic membership, or select **Users with entitlements** and choose the entitlements that define membership. To follow a group, choose that group's membership entitlement. +4. Configure **Requestable**, **Request policy**, and **Revoke policy** as needed. Review any warnings about approval and removal behavior, then click **Save**. + +The capability summary shows the linked **Access profile**, **Auto membership**, and **Requestable** state. Automatic membership and approval settings determine when matching users receive access and what happens when they stop matching. Other sources of access can keep a member's access active. + +If the profile uses a CEL rule, click **Edit rule** to change it in the access profile. Use **Open access profile** for settings outside the **Edit access** drawer. If the summary shows **Bundle off**, configure the access profile so membership grants its bundled Edge entitlements; profile membership alone isn't enough. + +## What callers see after you grant access + +Once a person holds the entitlements: + +- C1 Multipass lists the Edge, and its **Route AI traffic through Edge** setting can use it. See [Route other tools through C1 Multipass](/product/admin/connect-edge-gateway-multipass). +- The Edge appears under **Model endpoints** in their **AI & API** > **Inference API keys** page when **Allow long-lived API keys** is on. This setting isn't needed for the Multipass key helper. See [Use long-lived API keys](/product/admin/inference-api-keys). + +Share the guide for their client: [Claude Code](/product/admin/claude-code-edge-gateway-multipass), [Codex](/product/admin/edge-gateway-codex), or [other tools through local routing](/product/admin/connect-edge-gateway-multipass). Application developers can use [Connect your own application](/product/admin/edge-gateway-connect). diff --git a/product/admin/edge-gateway-codex.mdx b/product/admin/edge-gateway-codex.mdx new file mode 100644 index 000000000..16165baed --- /dev/null +++ b/product/admin/edge-gateway-codex.mdx @@ -0,0 +1,131 @@ +--- +title: Use Codex with Edge Gateway +description: Configure Codex to call your organization's Edge Gateway with short-lived C1 Multipass credentials on a desktop or an enrolled Linux server. +og:title: Use Codex with Edge Gateway - C1 docs +og:description: Configure Codex to call your organization's Edge Gateway with short-lived C1 Multipass credentials on a desktop or an enrolled Linux server. +sidebarTitle: Codex +--- + +{/* Editor Refresh: 2026-10-28 */} + + +**Early access.** This feature is in early access, which means it's undergoing ongoing testing and development while we gather feedback, validate functionality, and improve outputs. Contact the C1 Support team if you'd like to try it out or share feedback. + + +Run Codex through your organization's Edge Gateway without a provider API key. On a desktop, Codex uses C1 Multipass command-based authentication to renew short-lived tokens and calls the Edge directly over HTTPS. On an enrolled Linux server, Codex uses the Multipass fleet CLI's local routing endpoints. + +## Before you begin with Codex and Edge Gateway + +Confirm these prerequisites before configuring Codex: + +- Codex 0.118 or later is installed. +- On macOS, C1 Multipass and its command line tool are installed, signed in to your tenant, the device registered, and the app unlocked. Follow [Set up Multipass](/product/admin/connect-edge-gateway-multipass#set-up-multipass). The inference-helper CLI isn't available on Windows. +- On Linux servers, an enrolled Multipass runtime and `c1-multipass-fleet` are available. Follow the [Linux service routing setup](/product/admin/connect-edge-gateway-multipass#turn-on-edge-gateway-routing). +- Your C1 admin has granted you **List models** and **Call models** on an Edge with a route whose native format is **OpenAI Responses** and whose model supports your Codex workload. Set Codex's model to that route's **Route ID**. OpenAI Chat and Anthropic Messages routes aren't interchangeable with a Responses route. For an OpenAI model, select the **Responses** variant, not **Chat**. See [Configure inference routes](/product/admin/edge-gateway-inference-routing) and [Grant access to an Edge](/product/admin/edge-gateway-access). +- Make sure **Cross-App Access** is on under **AI** > **Cross-App Access** so Multipass can get Edge tokens for people. The Edge's **Overview** warns if it's off. If the setting isn't available, contact the C1 Support team. See [Enable enterprise-managed authorization](/product/admin/enterprise-managed-authorization/enable). + +The Multipass helper renews short-lived tokens automatically. It doesn't require **Allow long-lived API keys**. Use the desktop configuration or the enrolled-server configuration below, not both for the same Codex session. + +## Configure Codex on a desktop + +Use Codex 0.118 or later for command-based provider authentication. On the Edge's **Overview** tab, open **Connect your tools** > **Codex** and select **Desktop**. Copy the configuration into `~/.codex/config.toml`, preserving your existing configuration. You don't need to turn on local routing or load its environment for this path. + + + The Codex tab with Desktop selected and the start of config.toml, showing the edge profile, Edge model provider, and a generated example model. + + +The screenshot's model is a generated example. Replace it with a Responses-native route published on your Edge. + +The configuration has this form; replace the inference host, app ID, Edge ID, and model route ID with your Edge's values. See [Find the Edge's connection values](/product/admin/edge-gateway-connect#find-the-edges-connection-details). + +```toml +[profiles.edge] +model_provider = "edge" +model = "" + +[model_providers.edge] +name = "Edge" +base_url = "https:///v1" +wire_api = "responses" +requires_openai_auth = false +supports_websockets = false + +[model_providers.edge.auth] +command = "c1-multipass" +args = ["inference", "helper", "--edge-url", "https://", "--inference-resource", "https:///api/v1/apps//edges/", "--dial-only"] +timeout_ms = 10000 +refresh_interval_ms = 180000 +``` + +The helper uses the inference origin, while the provider base URL adds `/v1`. If `c1-multipass` isn't on Codex's `PATH`, use the command's full path. Merge these tables rather than defining an existing table twice. + +Start Codex with the generated profile: + +```bash +codex --profile edge +``` + +Codex now uses the Edge profile and its short-lived credentials. Use a route whose native format is OpenAI Responses. Don't substitute a provider model name unless it is also the route ID. + +If you previously loaded a local routing environment, remove its uppercase `HTTPS_PROXY` setting for this direct connection: + +```bash +env -u HTTPS_PROXY codex --profile edge +``` + +This removes only the uppercase `HTTPS_PROXY` variable for this command, not other proxy variables or system proxy settings. + +## Configure Codex on an enrolled server + +On an enrolled Linux host, configure Codex to use the Multipass fleet CLI's local inference endpoint. This path uses local routing rather than the desktop inference helper. + +Add the following provider to `~/.codex/config.toml`, preserving your existing configuration. If `c1edge` is already defined, merge the settings or choose a different provider name and use it in the launch command below. + +```toml +[model_providers.c1edge] +name = "C1 Edge through Multipass" +base_url = "http://127.0.0.1:18080/v1" +wire_api = "responses" +env_key = "OPENAI_API_KEY" +requires_openai_auth = false +supports_websockets = false +``` + +The base URL above uses Multipass's default inference port. If your host uses a different address or port, set `base_url` to the `OPENAI_BASE_URL` value reported by the routing environment below. Enter the URL itself in TOML, not the environment variable name. + +Select the Edge, start local routing, and load its environment into the current shell: + +```bash +c1-multipass-fleet edge select / +c1-multipass-fleet edge start +eval "$(c1-multipass-fleet edge env)" +``` + +The `eval` command executes the shell exports printed by Multipass, including `OPENAI_BASE_URL`, `OPENAI_API_KEY`, and `HTTPS_PROXY`. The API key is a local routing credential, not an upstream provider key. Avoid running `edge env` by itself, because its output includes the credential. + +Start Codex from that same shell, explicitly selecting the configured provider and a Responses-native route ID: + +```bash +codex -c 'model_provider="c1edge"' -m +``` + +Codex reads the endpoint from the provider's `base_url` and the local credential from `OPENAI_API_KEY`. Setting `OPENAI_BASE_URL` alone doesn't select this provider. Run the environment-loading command in each new shell and again if the local key changes after a Multipass service restart. + +See [Route other tools through C1 Multipass](/product/admin/connect-edge-gateway-multipass) for the local endpoints, Linux service configuration, and trust bundle for outbound HTTPS traffic. + +## Troubleshoot Codex with Edge Gateway + +Use the symptom to check the client configuration or ask your C1 admin to check the route: + +| Symptom | What to do | +| :--- | :--- | +| Codex doesn't recognize command-based authentication | Use Codex 0.118 or later. | +| Codex can't find `c1-multipass` | Use the installed command's full path in `[model_providers.edge.auth]`. See [Set up Multipass](/product/admin/connect-edge-gateway-multipass#set-up-multipass). | +| The helper reports a missing session or refuses the connection | Open and unlock Multipass, and confirm the device is registered. Ask your admin to check Cross-App Access and your **List models** and **Call models** grants. | +| The route or model isn't found | Use the Edge's exact **Route ID**, not the provider model name. Confirm the route is published and the Edge is on. | +| A request fails with a format or compatibility error | Select a route whose native format is OpenAI Responses and a model that supports the requested Codex features. Chat and Messages routes don't accept Responses requests. | +| Desktop Codex still uses local routing | Check for `HTTPS_PROXY` from a previous routing session. Use the direct-launch command above and check other proxy settings separately. | +| Server Codex doesn't use the selected Edge | Load the environment with `eval "$(c1-multipass-fleet edge env)"`, then launch with `-c 'model_provider="c1edge"'` from the same shell. Check that `[model_providers.c1edge].base_url` matches the local inference URL, including any custom port. See [Troubleshoot Edge Gateway routing](/product/admin/connect-edge-gateway-multipass#troubleshoot-edge-gateway-routing). | +| Server Codex reports a missing `OPENAI_API_KEY` | Load the fleet routing environment in the shell that launches Codex. Reload it after a Multipass service restart if the local key changes. | + +For clients that can't use Multipass, see [Use long-lived API keys](/product/admin/inference-api-keys). An admin must turn on **Allow long-lived API keys** before those clients can use a `c1llm_` key. diff --git a/product/admin/edge-gateway-connect.mdx b/product/admin/edge-gateway-connect.mdx new file mode 100644 index 000000000..cae977f55 --- /dev/null +++ b/product/admin/edge-gateway-connect.mdx @@ -0,0 +1,97 @@ +--- +title: Connect your own application +description: Connect your application to Edge Gateway using its inference endpoint, audience, resource, and scopes to request short-lived tokens and call models. +og:title: Connect your own application - C1 docs +og:description: Connect your application to Edge Gateway using its inference endpoint, audience, resource, and scopes to request short-lived tokens and call models. +sidebarTitle: Your own application +--- + +{/* Editor Refresh: 2026-10-28 */} + + +**Early access.** This feature is in early access, which means it's undergoing ongoing testing and development while we gather feedback, validate functionality, and improve outputs. Contact the C1 Support team if you'd like to try it out or share feedback. + + +Connect your application to an Edge Gateway by exchanging the caller's C1 identity for a short-lived inference token. Use the Edge's connection values to request the token, then send model requests to its inference endpoint. + +## Find the Edge's connection details + +The **Connection details** card fills in once the Edge is turned on. + + + +Open the Edge: **Apps** > *your app* > **Edge** > *your Edge*. + + +On the **Overview** tab, scroll to **Connection details**. + + + + + The Connection details card showing the Audience, the Inference resource, and the inference.models.read and inference.invoke scopes. + + +| Value | Format | Used for | +| :--- | :--- | :--- | +| **Audience** | `https://.edge.` | The token audience. All Edges in your tenant share it. | +| **Inference resource** | `https://-inference.edge./api/v1/apps//edges/` | Identifies this Edge when a caller requests a token | +| **Inference endpoint** | The inference resource up to, but not including, `/api` | The base URL callers send model requests to | +| **Scopes** | `inference.models.read`, `inference.invoke` | The access a token carries; matches the Edge's entitlements | + +The app ID and Edge ID also appear in the Edge's URL in C1. + +## Before you connect your application + +For a browser application that signs users in through C1 and exchanges their OIDC ID tokens for Edge grants, confirm these prerequisites: + +- **C1 SSO is enabled and configured for your application.** Configure the application's OIDC client and redirect URI so users can sign in and your application can obtain a C1-issued ID token. Contact the C1 Support team if C1 SSO isn't available for your tenant. +- **Cross-App Access is enabled.** Open **AI** > **Cross-App Access** and make sure the setting is turned on so C1 can issue ID-JAGs. See [Enable enterprise-managed authorization](/product/admin/enterprise-managed-authorization/enable). + +The C1 SSO prerequisite applies to the application's OIDC sign-in flow. Multipass device-session and workload-federation exchanges use their own authentication methods. Redeeming an ID-JAG at the Edge doesn't perform a separate C1 SSO sign-in. + +## Connect your own application to the Edge + +An application exchanges its signed-in user's C1 identity for an **ID-JAG**, then redeems that grant at the Edge for an **inference access token**. The ID-JAG is not an inference bearer token; sending it directly to `/v1/models` or an inference operation returns `401`. + +Your application needs an OAuth client that can obtain a C1 ID-JAG and generate DPoP proofs. See [Enterprise-managed authorization](/product/admin/enterprise-managed-authorization/overview) for the identity-exchange flow. DPoP proves that the application holds the private key bound to the grant. + +1. Generate a proof key and request an ID-JAG from C1 for the Edge's **Audience**, **Inference resource**, and required scopes. Bind the grant to this key using a DPoP proof in the C1 exchange. Handle any DPoP nonce challenge from C1 with a new proof containing the supplied nonce. +2. Create a fresh DPoP proof for `POST https:///oauth2/inference/token`, signed with the **same key**. Its public-key thumbprint must match the ID-JAG's `cnf.jkt`. Use the exact inference origin from **Connection details**, without a `/v1` suffix, when constructing the token endpoint URL. +3. Redeem the ID-JAG at that endpoint using the JWT bearer grant, as shown below. Supply the exact inference resource and a space-separated list of scopes contained in the grant. For discovery and inference, request `inference.models.read inference.invoke`. + +The following request illustrates the redemption step. Have your OAuth client supply `EDGE_ID_JAG` and `EDGE_DPOP_PROOF`; they are credentials, not literal placeholder strings. Set `EDGE_INFERENCE_URL` to the inference origin and `EDGE_INFERENCE_RESOURCE` to the complete inference resource from **Connection details**. + +```bash +EDGE_TOKEN_RESPONSE="$(curl --fail-with-body --silent --show-error \ + "$EDGE_INFERENCE_URL/oauth2/inference/token" \ + -H "Content-Type: application/x-www-form-urlencoded" \ + -H "DPoP: $EDGE_DPOP_PROOF" \ + --data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer' \ + --data-urlencode "assertion=$EDGE_ID_JAG" \ + --data-urlencode "resource=$EDGE_INFERENCE_RESOURCE" \ + --data-urlencode 'scope=inference.models.read inference.invoke')" +``` + +The JSON response contains `access_token`, `token_type` (`Bearer`), `expires_in` (seconds), `scope`, and `resource`. The access token starts with `tb_inf_at_v1.`. Keep the response private; don't print it or save it to logs. In application code, check for a successful HTTP response before reading `access_token`. + +4. Extract `access_token` from the response and send it in the `Authorization: Bearer` header when calling the inference endpoint. DPoP is required for the grant exchange; subsequent calls using this inference bearer token don't need a DPoP header. +5. Use `/v1/models` to discover the routes available to the caller, then send model requests in a format supported by the selected route. See [Configure inference routes](/product/admin/edge-gateway-inference-routing) for route IDs and request formats. + +An ID-JAG can be redeemed only once. Generate a new proof for each token request; reusing a redeemed grant or proof is rejected. + +Edge Gateway checks the token and the caller's access before forwarding each request with your organization's provider credentials. The application doesn't need the provider key. + +For applications that can't use short-lived tokens or C1 Multipass, see [Use long-lived API keys](/product/admin/inference-api-keys). An admin must turn on **Allow long-lived API keys** before those clients can use a `c1llm_` key. + +## Renew inference access + +Your application must renew inference access frequently. While the user's C1 ID token remains valid, it can obtain and redeem new ID-JAGs without asking the user to sign in again. When that ID token expires, repeat the C1 sign-in flow; the user may need to sign in interactively. The SSO configuration's **Assertion lifetime** controls how long the ID token remains valid. + +## Troubleshoot Edge connection details + +| Symptom | What to do | +| :--- | :--- | +| **Inference resource** and **Scopes** show "—" | Turn on the Edge. These values appear once it's on. | +| A long-lived inference API key is rejected | Check **Allow long-lived API keys** on the **Inference** tab. This setting doesn't control the Multipass key helper. | +| Callers see "You don't have access to an Edge" | Grant them **List models** and **Call models**. See [Grant access to an Edge](/product/admin/edge-gateway-access). | +| Callers can list models but requests fail with `403` | Grant **Call models** as well as **List models**. | diff --git a/product/admin/edge-gateway-inference-routing.mdx b/product/admin/edge-gateway-inference-routing.mdx new file mode 100644 index 000000000..48cf244e7 --- /dev/null +++ b/product/admin/edge-gateway-inference-routing.mdx @@ -0,0 +1,304 @@ +--- +title: Configure inference routes +description: Choose the model names, provider formats, credentials, and routing behavior your Edge Gateway exposes to clients. +og:title: Configure inference routes - C1 docs +og:description: Choose the model names, provider formats, credentials, and routing behavior your Edge Gateway exposes to clients. +sidebarTitle: Inference routes +--- + +{/* Editor Refresh: 2026-10-28 */} + + +**Early access.** This feature is in early access, which means it's undergoing ongoing testing and development while we gather feedback, validate functionality, and improve outputs. Contact the C1 Support team if you'd like to try it out or share feedback. + + +Publish stable model names for your clients, choose the providers behind them, and decide whether each request uses one model, an ordered backup chain, or smart routing. + +Use this reference after [setting up an Edge](/product/admin/edge-gateway-setup). Open **Apps** > *your app* > **Edge** > *your Edge* > **Inference** to manage providers and routes. For endpoints and authentication for a custom client, see [Connect your own application](/product/admin/edge-gateway-connect). + +## How routes, models, and formats fit together + +A **route** is the model name a client calls. A **target** is a provider model behind that route. One route can contain one target, an ordered list of targets, or groups of targets for smart routing. + +The client's model name and the provider's model name have different jobs: + +| Setting | What it controls | When to use it | +| :--- | :--- | :--- | +| **Route ID** | The value clients send in the request's `model` field. Use 1–64 lowercase letters, numbers, dots, underscores, or hyphens. | Give clients a stable name, such as `coding-default`, while you change the provider model behind it. | +| **Client format** (native format) | The request and response API clients use. | Match the API your tool sends, not just the provider's name. | +| **Provider** and provider profile | The upstream API, supported format, and authentication method for a target. Some providers offer more than one API. | Choose a compatible provider API for every target, including backups and judges. | +| **Upstream model ID** | The model identifier the Edge sends to the provider. | Select a suggestion or enter the exact provider model ID your account can use. | +| **Vault** and **Secret** | The provider API key the Edge reads, not a credential the caller receives. | Connect an API-key provider. A target can use the provider's saved key or its own key override. | +| **AWS region** | The region for a Bedrock target that uses AWS workload identity. | Use Bedrock without storing an API key in a vault. | + +An Edge holds up to **40 routes**. A route holds up to **16 targets**. + +### Match the client's API format + +Choose the format before adding backups. Every target in a route must support the route's native format. A shared provider or model family doesn't make different APIs interchangeable. + +| Native format | Caller API | Typical use | +| :--- | :--- | :--- | +| **Anthropic Messages** | `POST /v1/messages` | Claude Code and Anthropic Messages clients. | +| **OpenAI Responses** | `POST /v1/responses` | Codex configured with `wire_api = "responses"` and Responses clients. | +| **OpenAI Chat** | `POST /v1/chat/completions` | Chat Completions clients using OpenAI, Together, Fireworks, or Gemini Developer API. | + +OpenAI offers both Responses and Chat profiles. The Gemini Developer API, Together, and Fireworks examples below use Chat, not Responses. A route that accepts Messages can't use a Chat-only backup. If you change a single-model route's format, update callers to the matching endpoint too. + +**Bedrock Converse** is an upstream Bedrock API, not a fourth client format in this editor. With **Bedrock API** set to **Runtime · Converse**, callers use **OpenAI Chat**. Other Bedrock API profiles use Messages, Responses, or Chat; select the profile that matches your client and supply its AWS region. + +### Choose a suggested model or type an ID + +Use **Add models** to publish individual provider models, or **New route** to set your own Route ID and routing behavior. + +Suggestions combine registered models available to your organization's rollout channel, models referenced by saved routes, and provider catalog suggestions. Registering a model doesn't by itself make it available in your channel. Suggestions aren't a live check that your provider account can call a model. + +If the picker doesn't list your model, type its full upstream ID and select the offered option. A typed ID still has to satisfy the provider's grammar and be supported by the Edge runtime and your provider account. + +| Provider | Upstream model ID rule | Example-only placeholder ID | +| :--- | :--- | :--- | +| Anthropic | A bare `claude-` ID using the simple-ID characters below. | `claude-example-model` | +| OpenAI | A bare simple ID; not a URL or API path. | `gpt-example-model` | +| Together | Exactly `owner/model`, with a simple ID in each segment. | `example-org/example-chat-model` | +| Fireworks | The full `accounts//models/` path. Each variable segment has alphanumeric ends and contains only letters, numbers, dots, underscores, or hyphens. | `accounts/example-account/models/example-chat-model` | +| Gemini Developer API | A bare `gemini-` simple ID. Don't include `models/`, a URL, a path, or a query string. | `gemini-example-model` | + +A simple ID has 1–200 characters, starts and ends with a letter or number, and contains only letters, numbers, dots, underscores, colons, or hyphens internally. Fireworks account and model segments each allow up to 128 characters; the complete upstream ID must fit the 255-character target limit. Together's complete ID must also fit that limit. + +## Choose routing behavior + +Select **Direct**, **Failover**, or **Smart routing** in a route's **Routing** section. + +### Direct: choose one provider model + +Use **Direct** when you want a predictable provider and model for a workload, or when the client requires a specific model. Set the provider, upstream model ID, and key or AWS region. Callers continue to use the route ID even if you later replace the upstream model. + +### Failover: try compatible targets in order + +Use **Failover** when you want a backup for transient provider failures or timeouts. Configure **Primary**, then **Backup 1**, **Backup 2**, and any additional backups. Use **Move up** and **Move down** to change the attempt order. + +Keep every target on the same native format. A compatible cross-provider chain is Together Chat followed by Fireworks Chat; Anthropic Messages followed by Together Chat is not. + +Set **Attempt timeout (ms)** for the chain. **Route deadline (ms)** and **Maximum attempts** bound the overall work. Failover is not a way to bypass a rejected provider key, an authorization denial, or an invalid request. + +Targets run one at a time, not in parallel. The shared attempt and deadline budgets can stop a request before every backup is reached. Before response commitment, an attempt timeout, a transport failure, a recognized context-window error, or a transient rate-limit or overload error can advance to a backup. Provider authentication and billing or quota-exhaustion rejections are terminal by default; a `429` isn't automatically retryable. + +A whole-route deadline, cancellation, or exhausted attempt budget stops further attempts. Once the Edge commits a streaming response, a later stream failure doesn't restart the request on another target. + +### Smart routing: configure efficient and capable stages + +Use **Smart routing** (stage routing) when you want one route to select between efficient and capable model groups rather than treating every target as an equivalent backup. + +The UI exposes: + +| Option | Use it to | +| :--- | :--- | +| **Start with** / **Add efficient model** | Configure the efficient-stage target chain. | +| **Escalate to** / **Add capable model** | Configure the capable-stage target chain. | +| **Stage picker** | Choose the default stage when routing is undecided: **Efficient first** defaults to efficient; **Capable first** defaults to capable. | +| **Confidence threshold** and **Recent window** | Tune how conversation and tool signals influence stage selection. | +| **Use a judge model** | Consult an optional capability judge when signals don't confidently select a stage. The judge votes on routing; it doesn't answer the user. | +| Tier prompts and escalation/de-escalation notes | Customize the instructions used around stage transitions. | +| Judge thresholds, window, max output tokens, and prompt | Tune the optional judge separately from the stage picker. | + +All stage targets and the judge must match the route's native format. Routing considers conversation and tool signals, then the optional judge, then the picker mode's default stage. Signals or the judge can select the other stage, so **Start with** doesn't guarantee that every request first calls an efficient model. + +If the judge fails or returns no usable score, routing falls back to the mode's default stage. This doesn't bypass authorization, attempt budgets, or the route deadline. The editor doesn't expose a switch to make judge failure fail the caller's request; runtime-local routing settings aren't additional options in this UI. + +### Optional: tune timeouts, retries, and model settings + +Use these settings to bound provider work or satisfy a workload's model requirements. They don't change the client-facing route ID. + +| Setting group | When to use it | +| :--- | :--- | +| **Timeouts and retries** | Bound a provider attempt, the whole route, and the number of attempts. Turn on **Retry failed attempts** to configure delay, delay cap, same-target retries, and jitter. | +| Reasoning effort and context length | Override a target's model settings for this workload. Leave reasoning effort unset to use the client's setting. | +| Circuit breaker | Temporarily avoid a target after repeated qualifying availability or transport failures, using a failure threshold and cooldown. Not every timeout or provider error counts toward opening the circuit. | +| **When credentials fail** | Control supported handling of unavailable credentials. Rejected provider keys stop the request; terminal targets and judges must stop on credential failures. | +| A target's own key or AWS region | Use different credentials or a region for that target instead of the provider's shared settings. | + +## Worked routing examples + +These examples show field relationships, not model-version recommendations. All IDs containing `example` are **illustrative placeholders**, not real models to publish. Replace them with model IDs your provider account can call. A syntactically accepted ID doesn't prove that the model exists or that your account has access. + +Create the direct and failover examples from **Inference** > **Routes** > **New route**. Choose the format-compatible provider API, enter the table's fields, and click **Create route**. + +For requests, set `EDGE_INFERENCE_URL` to your Edge's inference origin, without a trailing slash, `/v1`, or `/api` path. Set `EDGE_INFERENCE_RESOURCE` to the inference resource from **Connection details**. Get a short-lived token from the Multipass helper: + +```bash +export EDGE_INFERENCE_URL="https://" +export EDGE_INFERENCE_RESOURCE="${EDGE_INFERENCE_URL}/api/v1/apps//edges/" +EDGE_TOKEN="$(c1-multipass inference helper \ + --edge-url "$EDGE_INFERENCE_URL" \ + --inference-resource "$EDGE_INFERENCE_RESOURCE" \ + --dial-only)" +``` + +Keep `EDGE_TOKEN` private and request a new token when it expires. It is a caller credential, not a provider API key. Follow [Set up Multipass](/product/admin/connect-edge-gateway-multipass#set-up-multipass) for device and CLI setup, or the [Claude Code key-helper guide](/product/admin/claude-code-edge-gateway-multipass) for client configuration. Callers need [List models and Call models access](/product/admin/edge-gateway-access). Long-lived keys are a separate, optional method described in [Use long-lived API keys](/product/admin/inference-api-keys). + +### Example 1: Anthropic Messages for Claude Code + +Use a stable Messages route for Claude Code while keeping the upstream Claude model under admin control. + +| UI field | Example value | +| :--- | :--- | +| **Provider** | Anthropic | +| **Route ID** | `claude-team` | +| **Routing** | Direct | +| **Client format** (native format) | Anthropic Messages | +| **Upstream model ID** | `claude-example-model` — replace with your Claude model ID. | +| **Key** | Your Anthropic API key secret selected from a vault. | + +Send a Messages request to the Edge, using the route ID rather than the upstream model ID: + +```bash +curl "$EDGE_INFERENCE_URL/v1/messages" \ + -H "Authorization: Bearer $EDGE_TOKEN" \ + -H "Content-Type: application/json" \ + -H "anthropic-version: 2023-06-01" \ + -d '{"model":"claude-team","max_tokens":128,"messages":[{"role":"user","content":"Reply with a short greeting."}]}' +``` + +For Claude Code, set `ANTHROPIC_MODEL` to `claude-team` in the generated configuration. C1's generated settings choose a main model from recognized Claude route names when one is available; if your route has a custom name, explicitly select it. See [Configure Claude Code](/product/admin/claude-code-edge-gateway-multipass#configure-claude-code-to-use-edge-gateway). + +### Example 2: OpenAI Responses for Codex + +Use a Responses route for Codex's Responses wire protocol. A Chat-only route isn't a substitute. + +| UI field | Example value | +| :--- | :--- | +| **Provider** | OpenAI | +| **Route ID** | `codex-team` | +| **Routing** | Direct | +| **Client format** (native format) | OpenAI Responses | +| **Upstream model ID** | `gpt-example-model` — replace with your Responses-capable model ID. | +| **Key** | Your OpenAI API key secret selected from a vault. | + +```bash +curl "$EDGE_INFERENCE_URL/v1/responses" \ + -H "Authorization: Bearer $EDGE_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{"model":"codex-team","input":"Reply with a short greeting."}' +``` + +In Codex, set the profile's `model` to `codex-team`, keep `wire_api = "responses"`, and use the Edge inference origin plus `/v1` as the provider base URL. Copy the rest of the helper configuration from [Use Codex with Edge Gateway](/product/admin/edge-gateway-codex#configure-codex-on-a-desktop). + +### Example 3: Together OpenAI Chat + +Use Together when your client sends Chat Completions and your provider model ID includes its owner. + +| UI field | Example value | +| :--- | :--- | +| **Provider** | Together | +| **Route ID** | `together-chat` | +| **Routing** | Direct | +| **Client format** (native format) | OpenAI Chat | +| **Upstream model ID** | `example-org/example-chat-model` — replace both segments with the provider's ID. | +| **Key** | Your Together API key secret selected from a vault. | + +```bash +curl "$EDGE_INFERENCE_URL/v1/chat/completions" \ + -H "Authorization: Bearer $EDGE_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{"model":"together-chat","messages":[{"role":"user","content":"Reply with a short greeting."}]}' +``` + +### Example 4: Fireworks OpenAI Chat + +Use the full Fireworks account-scoped upstream ID, while exposing a shorter route ID to clients. + +| UI field | Example value | +| :--- | :--- | +| **Provider** | Fireworks | +| **Route ID** | `fireworks-chat` | +| **Routing** | Direct | +| **Client format** (native format) | OpenAI Chat | +| **Upstream model ID** | `accounts/example-account/models/example-chat-model` — replace the account and model segments. | +| **Key** | Your Fireworks API key secret selected from a vault. | + +```bash +curl "$EDGE_INFERENCE_URL/v1/chat/completions" \ + -H "Authorization: Bearer $EDGE_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{"model":"fireworks-chat","messages":[{"role":"user","content":"Reply with a short greeting."}]}' +``` + +### Example 5: Gemini Developer API OpenAI Chat + +Use Gemini Developer API with a Chat Completions client and an API key. This provider profile uses Google's Generative Language API, not Vertex AI. C1 expects an API key, not an OAuth token or service-account JSON file. + +#### Get a Gemini Developer API key + +Create or select a Cloud project in Google AI Studio and create a Gemini API key for it. Each key belongs to a Cloud project; it isn't specific to one model. For production quotas, use a billing-enabled project and review Google's [billing and usage tiers](https://ai.google.dev/gemini-api/docs/billing). + +Follow Google's [Gemini API key guide](https://ai.google.dev/gemini-api/docs/api-key) for current creation and restriction rules. New AI Studio authorization keys are restricted to the Generative Language API by default. If you use a standard key, explicitly restrict it to that API; Google rejects unrestricted standard keys. + +Store the key in a C1 vault as an **API key** secret. Grant the Edge's runtime identity **Open secret** access to that vault. Selecting a key in the picker doesn't itself grant secret access. Follow [Connect a provider and add models](/product/admin/edge-gateway-setup#connect-a-provider-and-add-models) to create the vault and secret and check runtime access. + +The Edge calls Google's OpenAI-compatible upstream endpoint at `https://generativelanguage.googleapis.com/v1beta/openai/chat/completions`, using the API key as a bearer credential. Your client still calls the Edge's `/v1/chat/completions` endpoint. See Google's [OpenAI compatibility guide](https://ai.google.dev/gemini-api/docs/openai). + +| UI field | Example value | +| :--- | :--- | +| **Provider** | Gemini Developer API | +| **Route ID** | `gemini-chat` | +| **Routing** | Direct | +| **Client format** (native format) | OpenAI Chat | +| **Upstream model ID** | `gemini-example-model` — replace with a bare documented `gemini-` ID, without `models/`. | +| **Key** | Your Gemini Developer API key secret selected from a vault. | + +Type the full ID if your model isn't suggested. The picker isn't live Gemini model discovery; publishing a route doesn't check your Google quota or prove model access. + +```bash +curl "$EDGE_INFERENCE_URL/v1/chat/completions" \ + -H "Authorization: Bearer $EDGE_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{"model":"gemini-chat","messages":[{"role":"user","content":"Reply with a short greeting."}]}' +``` + +### Example 6: Together-to-Fireworks failover + +Use two Chat-compatible providers to keep the client request format unchanged when a transient failure or timeout moves the request to a backup. + +| UI field | Primary | Backup 1 | +| :--- | :--- | :--- | +| **Provider** | Together | Fireworks | +| **Route ID** | `chat-resilient` (shared by the route) | Same route. | +| **Routing** | Failover | Same route. | +| **Client format** (native format) | OpenAI Chat | OpenAI Chat | +| **Upstream model ID** | `example-org/example-chat-model` | `accounts/example-account/models/example-chat-model` | +| **Key** | Your Together API key secret. | Your Fireworks API key secret. | + +Configure an attempt timeout, keep Together first, and click **Create route**. The models need not be identical, so evaluate whether both satisfy your application's behavior and feature requirements. Format compatibility alone doesn't establish equivalent tool support, context size, or output quality. + +```bash +curl "$EDGE_INFERENCE_URL/v1/chat/completions" \ + -H "Authorization: Bearer $EDGE_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{"model":"chat-resilient","messages":[{"role":"user","content":"Reply with a short greeting."}]}' +``` + +The caller sends one route ID. The Edge selects the target; the client doesn't send the backup's upstream ID. + +## Check route readiness and client selection + +Check the **Routes** table after saving. These statuses summarize configuration and reported runtime compatibility; **Ready** is not a successful test call to the provider. + +| Status | What to do | +| :--- | :--- | +| **Ready** | Select the route in a matching client and make a request. | +| **Needs conversion** | Open the older route and select **Convert to provider targets** before saving changes. Its existing model and vault references carry over. | +| **Choose a provider** | Select a provider for the route's targets. | +| **Review compatibility** | Match each target's provider profile to the route's client format. Update callers if you change the format. | +| **Needs a key** | Select a vault and API key secret, or supply the AWS region for a workload-identity target. | +| **Incomplete** | Fill in the missing provider profile or upstream model ID. | +| **Edge can't serve** | Review the provider's reported runtime compatibility. The connected Edge needs support for the selected profile. | +| **Can't read key** | Link the runtime identity and grant it access to the key's vault. Creating or selecting the secret alone isn't sufficient. | + +List the published route IDs available to the caller: + +```bash +curl "$EDGE_INFERENCE_URL/v1/models" \ + -H "Authorization: Bearer $EDGE_TOKEN" +``` + +Use an ID returned by the Edge, not an upstream model ID unless they happen to match. For Claude Code, verify `ANTHROPIC_MODEL` or your explicit model selection. For Codex, verify the profile's `model` and Responses format. Listing routes establishes discovery access; a successful inference request exercises the provider path. diff --git a/product/admin/edge-gateway-overview.mdx b/product/admin/edge-gateway-overview.mdx new file mode 100644 index 000000000..b55f9560b --- /dev/null +++ b/product/admin/edge-gateway-overview.mdx @@ -0,0 +1,84 @@ +--- +title: Edge Gateway overview +description: Give people and workloads governed access to AI models through an Edge Gateway, using your organization's provider keys, with every request attributed to the caller. +og:title: Edge Gateway overview - C1 docs +og:description: Give people and workloads governed access to AI models through an Edge Gateway, using your organization's provider keys, with every request attributed to the caller. +sidebarTitle: Overview +--- + +{/* Editor Refresh: 2026-10-28 */} + + +**Early access.** This feature is in early access, which means it's undergoing ongoing testing and development while we gather feedback, validate functionality, and improve outputs. Contact the C1 Support team if you'd like to try it out or share feedback. + + +Use an Edge Gateway to give coding tools, agents, and apps access to AI models without handing out provider API keys. Callers sign in as themselves, C1 checks that they're entitled to the Edge, and the Edge calls the model provider with your organization's key. Every request is attributed to the person or service principal who made it. + +## What an Edge Gateway does + +An Edge is a gateway that belongs to an application in C1. An Edge can serve **models**, **egress** (outbound internet access), or both. These pages cover serving models. + +For models, an Edge: + +- Holds your provider keys in a C1 vault, so callers never see them. +- Publishes **routes**: the model names callers send, each mapped to one or more provider models. +- Grants access through two entitlements on its parent app: **List models** (`inference.models.read`) and **Call models** (`inference.invoke`). +- Accepts OpenAI-compatible and Anthropic-compatible requests, such as `/v1/models`, `/v1/chat/completions`, `/v1/responses`, and `/v1/messages`, and forwards them to the provider. + +## How a request flows through an Edge Gateway + +A caller never presents a provider key. The flow for every request is: + +1. The caller signs in to C1 as a person or a service principal. +2. The caller gets a short-lived token for the Edge, scoped to the Edge's **inference resource** and the scopes it was granted. +3. The caller sends the model request to the Edge's inference endpoint with that token. +4. The Edge checks the token and the route, then calls the provider with the key stored on the route. + +C1 Multipass gets short-lived credentials for people on their own devices and for enrolled service hosts. Long-lived inference API keys are an advanced option for clients that can't use Multipass. + +## Set up an Edge Gateway + +Admins set up an Edge in this order. Each step has its own page: + +| Step | What you do | Page | +| :--- | :--- | :--- | +| 1 | Add an Edge to an app, link the runtime identity, add models, and turn the Edge on | [Set up an Edge for inference](/product/admin/edge-gateway-setup) | +| 2 | Grant people or service principals List models and Call models | [Grant access to an Edge](/product/admin/edge-gateway-access) | +| 3 | Share the guide for the caller's tool or application | Choose a connection method below | + +For route formats, provider targets, and failover, see [Configure inference routes](/product/admin/edge-gateway-inference-routing). + +Callers then connect with one of these methods: + +| Method | Best for | Page | +| :--- | :--- | :--- | +| C1 Multipass key helper for Claude Code | Claude Code on macOS, without enabling local routing | [Use Claude Code with Edge Gateway](/product/admin/claude-code-edge-gateway-multipass) | +| C1 Multipass credentials for Codex | Codex on macOS or an enrolled Linux server, using a Responses-native route | [Use Codex with Edge Gateway](/product/admin/edge-gateway-codex) | +| C1 Multipass local endpoints | Other tools, SDKs, and enrolled service hosts | [Route other tools through C1 Multipass](/product/admin/connect-edge-gateway-multipass) | +| Application token exchange | Your own application using the caller's C1 identity | [Connect your own application](/product/admin/edge-gateway-connect) | +| Long-lived inference API key | Clients that can't use C1 Multipass; requires **Allow long-lived API keys** | [Use long-lived API keys](/product/admin/inference-api-keys) | + +## Before you set up an Edge Gateway + +Confirm the following before you start: + +- Edge Gateway is enabled for your tenant. It's in early access; contact the C1 Support team to turn it on. +- You have a C1 admin role that can manage applications, service principals, and vaults. +- You have an API key for at least one supported model provider: Anthropic, OpenAI, Gemini Developer API, Together, or Fireworks. AWS Bedrock uses AWS workload identity instead of a key. +- Make sure **Cross-App Access** is on under **AI** > **Cross-App Access** so C1 can issue Edge tokens. The Edge's **Overview** warns if it's off. If the setting isn't available, contact the C1 Support team. See [Enable enterprise-managed authorization](/product/admin/enterprise-managed-authorization/enable). + +## Frequently asked questions about Edge Gateway + + + + Any application in C1. The Edge's entitlements, List models and Call models, live on that application, so choose the app whose owners should govern model access. You can't move an Edge to another app after you create it. + + + + No. Keys stay in a C1 vault that only the Edge's runtime identity can read. Callers only ever hold short-lived C1 tokens or an inference API key. + + + + Yes. An Edge can publish up to 40 routes, and routes can use different providers. A single route can also fail over between providers. + + diff --git a/product/admin/edge-gateway-quickstart.mdx b/product/admin/edge-gateway-quickstart.mdx new file mode 100644 index 000000000..5f0071e11 --- /dev/null +++ b/product/admin/edge-gateway-quickstart.mdx @@ -0,0 +1,117 @@ +--- +title: Make your first model call through Edge Gateway +description: Set up one model route, grant a developer access, and check a first Claude Code request through your Edge Gateway. +og:title: Edge Gateway quickstart - C1 docs +og:description: Set up one model route, grant a developer access, and check a first Claude Code request through your Edge Gateway. +sidebarTitle: Quickstart +--- + +{/* Editor Refresh: 2026-10-28 */} + + +**Early access.** This feature is in early access, which means it's undergoing ongoing testing and development while we gather feedback, validate functionality, and improve outputs. Contact the C1 Support team if you'd like to try it out or share feedback. + + +Give one developer access to one model through an Edge Gateway, then check their first request. An admin completes the setup and access steps; the developer configures a compatible client. This walkthrough uses Anthropic and Claude Code as the example. + +## Before you begin the Edge Gateway quickstart + +Confirm these prerequisites before starting: + +- Edge Gateway is enabled for your organization, and you have an admin role that can manage applications, service principals, and vaults. +- Make sure **Cross-App Access** is on under **AI** > **Cross-App Access** so Multipass can get Edge tokens for people. The Edge's **Overview** warns if it's off. If the setting isn't available, contact the C1 Support team. See [Enable enterprise-managed authorization](/product/admin/enterprise-managed-authorization/enable). +- You have an API key for a supported inference provider and the full model ID you want to serve. +- For the example below, the developer has Claude Code and C1 Multipass on macOS, with the command line tool installed, signed in, the device registered, and the app unlocked. See [Set up Multipass](/product/admin/connect-edge-gateway-multipass#set-up-multipass). + +The Edge setup and access steps also apply to other providers. Choose a client that matches your route's native API format; the Claude Code configuration below requires a Messages-compatible route. For other provider fields and calls, see: + +- **OpenAI** — [Responses routes for Codex](/product/admin/edge-gateway-inference-routing#example-2-openai-responses-for-codex). +- **Gemini Developer API** — [Chat routes with a key from Google AI Studio](/product/admin/edge-gateway-inference-routing#example-5-gemini-developer-api-openai-chat). +- **Together** — [Chat routes for open-weight models](/product/admin/edge-gateway-inference-routing#example-3-together-openai-chat). +- **Fireworks** — [Chat routes](/product/admin/edge-gateway-inference-routing#example-4-fireworks-openai-chat) with full `accounts//models/` IDs. + + +This helper-based walkthrough requires macOS; the inference-helper CLI isn't available on Windows. For platform details and installation, see [Set up Multipass](/product/admin/connect-edge-gateway-multipass#set-up-multipass). For Linux servers, use the [Multipass fleet setup](/product/admin/connect-edge-gateway-multipass#turn-on-edge-gateway-routing). + + +## Set up and check your first model request + +Use the same application and Edge throughout these steps. Leave **Allow long-lived API keys** off; the Multipass helper doesn't require it. + + + +Under **Apps**, open the application that will own your Edge. If you don't have one yet, click **New application** and [create an application](/product/admin/applications#create-a-new-application), then return here. + +Under **AI**, select **Edge**, then click **Add Edge**. Enter a name, keep **Inference** selected, and click **Create**. + +On the Edge's **Overview** tab, click **Link** beside **Runtime identity**. Select a service principal, or use **Create service principal** to create one inline. Click **Link existing principal** to save the binding; creating a principal alone doesn't link it. See [Set up an Edge](/product/admin/edge-gateway-setup). + + + +Open **Inference** > **Add models** and select your provider: **Anthropic** in this example. Choose a vault and API-key secret, or use **Create vault and secret** to store your provider key. Confirm the runtime identity can read the key. + +Under **Models**, enter the full Anthropic API model ID—for example, `claude-sonnet-5-5`—and select the offered option. Use a model your Anthropic API key can access; the example is illustrative. Use the complete ID from [Anthropic's model reference](https://platform.claude.com/docs/en/models/overview), including the `claude-` prefix. + +Registered-model suggestions depend on your organization's rollout channel; provider catalog suggestions can also appear. If your model isn't suggested, type its exact ID. Suggestions don't establish that your provider account can call the model. Click **Publish**, then note the **Route ID** in the routes table for the developer's configuration. If the published Route ID is `claude-sonnet-5-5`, use that value for `` in the configuration below. + + + +On **Overview**, keep **Who can call** set to **People who sign in**. Expand **Show checklist** if that setting is hidden. Open **Grants**, select **Inference** under **Members**, and click **Add member**. Select the developer, then click **Grant access**. This grants both **List models** and **Call models**; an access profile isn't required for this direct grant. See [Grant access to an Edge](/product/admin/edge-gateway-access). + + + +Click **Turn on** and choose **Enforce** for this walkthrough: + +- **Enforce** denies connections that the Edge's policy doesn't allow. +- **Observe** logs connections that policy would deny and allows them through; use it for testing rather than enforcement. + +Review **What turns on**, then click **Turn on**. + + + +For this Anthropic example, open **Connect your tools** > **Claude Code** on **Overview**. Have the developer merge the generated settings into `~/.claude/settings.json`; don't overwrite existing settings. The configuration has this form: + +```json +{ + "apiKeyHelper": "c1-multipass inference helper --edge-url https://-inference.edge. --inference-resource https://-inference.edge./api/v1/apps//edges/ --dial-only", + "env": { + "ANTHROPIC_BASE_URL": "https://-inference.edge.", + "ANTHROPIC_MODEL": "", + "CLAUDE_CODE_API_KEY_HELPER_TTL_MS": "60000" + } +} +``` + +Replace the placeholders with the Edge's connection values and published Claude route ID. Remove conflicting `ANTHROPIC_API_KEY` and `ANTHROPIC_AUTH_TOKEN` values from the environment. See [Use Claude Code with Edge Gateway](/product/admin/claude-code-edge-gateway-multipass) for helper checks and troubleshooting. + +For Codex 0.118 or later, follow [Use Codex with Edge Gateway](/product/admin/edge-gateway-codex) to configure a Responses-native route and the `edge` profile. + + + +Have the developer run a prompt from a terminal: + +```bash +env -u ANTHROPIC_API_KEY -u ANTHROPIC_AUTH_TOKEN -u HTTPS_PROXY \ + claude -p "Reply with exactly: edge ok" +``` + +For this direct Edge check, the command removes the uppercase `HTTPS_PROXY` variable set by Multipass local routing and the two named Anthropic credentials that could override the helper. It doesn't remove other proxy variables or system proxy settings; check those separately if the request still uses a proxy. + +Check the response, then open the Edge's **Activity** > **Flows** tab and choose a time range that includes the request. If the Edge also serves egress, select **Inference** first. Allow a few minutes for recent activity to appear, then look for the developer's request and check its **Outcome**. + +If the request doesn't appear in **Flows** after a few minutes, or Claude Code returns an error, see [Troubleshoot Claude Code](/product/admin/claude-code-edge-gateway-multipass#troubleshoot-claude-code-with-edge-gateway). + + + +## Continue configuring Edge Gateway + +Use the detailed guides for additional models, callers, and clients: + +- [Set up an Edge](/product/admin/edge-gateway-setup) +- [Configure inference routes and failover](/product/admin/edge-gateway-inference-routing) +- [Grant access](/product/admin/edge-gateway-access) +- [Use Claude Code with Edge Gateway](/product/admin/claude-code-edge-gateway-multipass) +- [Use Codex with Edge Gateway](/product/admin/edge-gateway-codex) +- [Route other tools through C1 Multipass](/product/admin/connect-edge-gateway-multipass) +- [Connect your own application](/product/admin/edge-gateway-connect) +- [Use long-lived API keys (advanced)](/product/admin/inference-api-keys) diff --git a/product/admin/edge-gateway-setup.mdx b/product/admin/edge-gateway-setup.mdx new file mode 100644 index 000000000..a96947052 --- /dev/null +++ b/product/admin/edge-gateway-setup.mdx @@ -0,0 +1,216 @@ +--- +title: Set up an Edge for inference +description: Create an Edge Gateway on an application, link its runtime identity, connect a model provider, publish model routes, and turn it on. +og:title: Set up an Edge for inference - C1 docs +og:description: Create an Edge Gateway on an application, link its runtime identity, connect a model provider, publish model routes, and turn it on. +sidebarTitle: Set up an Edge +--- + +{/* Editor Refresh: 2026-10-28 */} + + +**Early access.** This feature is in early access, which means it's undergoing ongoing testing and development while we gather feedback, validate functionality, and improve outputs. Contact the C1 Support team if you'd like to try it out or share feedback. + + +Set up an Edge to serve AI models to your organization: add it to an application, give it a runtime identity, connect a provider with your key, publish the models callers can use, and turn it on. For how the pieces fit together, see the [Edge Gateway overview](/product/admin/edge-gateway-overview). + +## Before you begin setting up an Edge + +- Edge Gateway is enabled for your tenant. +- You have a model provider API key, or an AWS account for Bedrock. +- You know which application should own the Edge. Its List models and Call models entitlements live on that app. +- Make sure **Cross-App Access** is on under **AI** > **Cross-App Access** so C1 can issue Edge tokens. The Edge's **Overview** warns if it's off. If the setting isn't available, contact the C1 Support team. See [Enable enterprise-managed authorization](/product/admin/enterprise-managed-authorization/enable). + +## Add an Edge to an application + +Each Edge belongs to one application. + + + +Go to **Apps** and open the application that should own the Edge. + + +In the app's left navigation, under **AI**, click **Edge**. + + +Click **Add Edge**. + + +Enter a **Name**. You can't rename an Edge after it's created. + + +Under **What will this Edge serve?**, keep **Inference** selected. Select **Egress** too only if this Edge will also control outbound internet access. You can remove a capability later, but you can't add one. + + +Click **Create**. + + + + + The Add an Edge dialog with acme-ai-gateway entered as the name, Inference selected, Egress unchecked, and Create enabled. + + +C1 opens the new Edge with its **Status** set to **Disabled** and a **Set up this Edge** checklist on the **Overview** tab. The **Turn on** button stays disabled until the required steps are done. + + + A new Edge's Overview tab showing the Set up this Edge checklist: Runtime identity and Models required, Who can call done by default, Grant access recommended, and Connect a coding tool after turn on. + + +## Link the runtime identity + +The runtime identity is the service principal the Edge runs as. It reads provider keys from your vaults. All inference Edges in a tenant share one runtime identity, so you only do this once. + + + +On the **Overview** tab, next to **Runtime identity**, click **Link**. + + +In **Existing service principal**, choose the service principal. If you need a new one and have permission to create it, click **Create service principal** and complete the creation drawer. C1 selects the new principal when you return. + + +Click **Link existing principal** to link the selected principal to the Edge. + + +Click **Close**. + + + +The **Runtime identity** step shows as done. If the service principal doesn't appear in the list yet, click **Refresh linked principals**. + +## Connect a provider and add models + +Add models from the **Inference** tab. Your provider key is stored in a C1 vault and saved on the routes that use it. + + + +Click the **Inference** tab, then **Add models**. + + +Under **1. Provider**, choose a provider. When more than one API is available, choose the matching **Client format** or **Bedrock API** profile. Match the caller's request format to that profile: + +| Provider | Request format | +| :--- | :--- | +| Anthropic | Anthropic Messages (`/v1/messages`) | +| OpenAI | OpenAI Responses (`/v1/responses`) or OpenAI Chat (`/v1/chat/completions`), depending on the selected profile | +| Gemini Developer API, Together, Fireworks | OpenAI Chat (`/v1/chat/completions`) | +| AWS Bedrock | OpenAI Chat for **Runtime · Converse**; other Bedrock API profiles use Messages, Responses, or Chat | + + +Under **2. Key**, choose the **Vault** and **Secret** that hold the provider's API key. To store a new key, click **Create vault and secret**: +- Create the vault. C1 is a member of the vault so the Edge can read its secrets, and C1 grants the Edge access to it. +- Create the secret with **Secret type** set to **API key**, and paste the key into **Secret value**. + +For AWS Bedrock, choose a region instead of a key. Bedrock uses AWS workload identity. + + +Under **3. Models**, search for a model or type its full provider model ID, then select it from the list. Fireworks model IDs use the form `accounts//models/`. Add as many models as you need. + + +Click **Publish**. + + + + + The Add models drawer with Anthropic selected, the acme-ai-keys vault and a secret displayed by its ID, vault access granted, claude-sonnet-4-5 selected, and Publish enabled. + + +Each selected model becomes a **route**. Use the **Route ID** shown in the table when calling the Edge; it can differ from the provider's model ID. An Edge can have up to 40 routes. Check each route's status before turning the Edge on. + +You can type or paste a model ID before choosing a key, but you must add the key before publishing. If the picker shows **No suggested models**, enter the full upstream model ID and select the offered option. For AWS Bedrock, add a region before publishing. + +The model picker combines registered models available to your organization's rollout channel, models referenced by saved routes, and provider catalog suggestions. Registration alone doesn't make a model appear in your channel. If a model isn't listed, type its full provider model ID and select the offered option. Publishing still depends on the provider and model configuration being supported by your Edge runtime. + +For routing modes and compatible provider targets, see [Configure inference routes](/product/admin/edge-gateway-inference-routing). + + + An Enforce-mode Edge with Anthropic marked Connected and two Ready routes: claude-sonnet-4-5 and coding-default. + + + +The Edge's runtime identity needs permission to read secrets in each key's vault. When you create the vault from **Add models**, C1 grants that access for you. If you pick an existing vault and the route shows **Can't read key**, grant the runtime identity access to that vault. + + +### Optional: Create a route with your own model name + +Create a route when you want callers to use a stable name, such as `coding-default`, instead of a provider's model ID, or when a route should try several models. + + + +On the **Inference** tab, under **Routes**, click **New route**. + + +Enter a **Route ID**: up to 64 lowercase letters, numbers, dots, underscores, and hyphens. Callers send this value as `"model"` in their requests. + + +Choose a **Routing** mode: +- **Direct**: one provider model. +- **Failover**: try models in order. If one fails, the next is tried. +- **Smart routing**: start on efficient models and move to capable models when needed, optionally with a judge model that decides. + + +Choose the **Provider** and enter the **Upstream model ID**. + + +**Optional.** Under **Advanced**, set timeouts, retries, reasoning effort, context length, a circuit breaker, and what to do when the provider rejects the key. + + +Click **Create route**. + + + + + An unsaved New route draft opened from coding-default, with Route ID coding-assistant, Direct routing, Anthropic, claude-sonnet-4-5, and Create route enabled. + + +The new route appears in the **Routes** table. Callers can now send `"model": "coding-default"`. + +## Choose who can call the Edge + +By default, an Edge accepts **People who sign in**. To configure a workload caller, open the **Overview** tab and click **Change** next to **Who can call**. Select **A workload**, choose its **Service principal** and **Workload federation trust**, then click **Save**. You can use **Create service principal** here if you have permission, but creating the principal doesn't save the Edge's caller settings. This choice applies to every route and decides who you can grant access to. + +## Optional: Allow long-lived API keys + +Turn on this setting only for clients that need a long-lived inference API key. It controls `c1llm_` keys, not the short-lived tokens issued by the Multipass key helper. + + + Allow long-lived API keys turned off, with an explanation that short-lived Multipass and Claude Code keys remain available to authorized users. + + + + +Click the **Inference** tab. + + +Turn on **Allow long-lived API keys**. The change saves immediately. + + + +The Edge now accepts long-lived inference API keys. Anyone holding one can use it with the key owner's access until it expires or is revoked. Leave this setting off when callers use the Multipass key helper or local endpoints. + +## Turn on the Edge + +Turn on the Edge once the **Setup** status reads **Ready to turn on**. + + + +Click **Turn on**. + + +Keep **Enforce** selected. **Enforce** denies connections the Edge's policy doesn't allow. **Observe** logs those connections and lets them through; it's mainly for testing egress rules. + + +Review **What turns on**, then click **Turn on**. + + + + + The Turn on acme-ai-gateway dialog with Enforce selected and a What turns on summary showing two model routes for people who sign in. + + +The Edge's **Status** changes to **Enforce**. If you haven't already granted access, [grant access to the Edge](/product/admin/edge-gateway-access) before callers connect. + +## Change, turn off, or delete an Edge + +- To switch between **Observe** and **Enforce**, click **Change mode**. +- To stop serving requests, turn the Edge off. Its routes, rules, and grants stay as they are. +- To delete the Edge, click the **...** (more actions) menu and select **Delete Edge**. diff --git a/product/admin/enterprise-managed-authorization/enable.mdx b/product/admin/enterprise-managed-authorization/enable.mdx index 40a416387..ef58b14c2 100644 --- a/product/admin/enterprise-managed-authorization/enable.mdx +++ b/product/admin/enterprise-managed-authorization/enable.mdx @@ -19,7 +19,7 @@ Enabling enterprise-managed authorization exposes the admin surfaces for registe -Go to **Settings** in the left navigation and select **Cross-App Access** under **AI**. +Open **AI** in the left navigation, then select **Cross-App Access** under **AI Gateway**. Click **Edit** in the top right of the **Cross-App Access** section. diff --git a/product/admin/inference-api-keys.mdx b/product/admin/inference-api-keys.mdx new file mode 100644 index 000000000..92e6f5cc7 --- /dev/null +++ b/product/admin/inference-api-keys.mdx @@ -0,0 +1,249 @@ +--- +title: Use long-lived API keys +description: Create, use, and rotate scoped long-lived inference API keys for clients that can't use C1 Multipass to call Edge Gateway. +og:title: Use long-lived API keys - C1 docs +og:description: Create, use, and rotate scoped long-lived inference API keys for clients that can't use C1 Multipass to call Edge Gateway. +sidebarTitle: Long-lived API keys (advanced) +--- + +{/* Editor Refresh: 2026-10-28 */} + + +**Early access.** This feature is in early access, which means it's undergoing ongoing testing and development while we gather feedback, validate functionality, and improve outputs. Contact the C1 Support team if you'd like to try it out or share feedback. + + +Create an inference API key in C1 when a tool, script, or server needs to call models through your organization's Edge Gateway and can't use C1 Multipass. An admin must turn on **Allow long-lived API keys** on the Edge first. The key is a bearer token tied to you and to one model endpoint. Edge Gateway validates the key and your access before forwarding requests. + +## When to use an inference API key + +Use a long-lived inference API key only when the client can't use C1 Multipass. Choose the short-lived option for supported tools and enrolled hosts: + +| Option | Best for | Credential | +| :--- | :--- | :--- | +| [Claude Code key helper](/product/admin/claude-code-edge-gateway-multipass) | Claude Code on macOS with C1 Multipass | Automatically renewed, short-lived tokens | +| [Codex with C1 Multipass](/product/admin/edge-gateway-codex) | Codex on macOS or an enrolled Linux server | Short-lived helper tokens on desktop, or local routing credentials on a server | +| [C1 Multipass local endpoints](/product/admin/connect-edge-gateway-multipass) | Other tools, SDKs, and enrolled service hosts | A local key that protects the device's loopback endpoints | +| Long-lived inference API key (this page) | Clients that can't use C1 Multipass | A key you create, store, and rotate | + +Turning off **Allow long-lived API keys** blocks `c1llm_` keys. It doesn't disable the Multipass key helper. + +When the setting is on, the Edge's **Overview** > **Connect your tools** card includes a **Long-lived API keys (advanced)** section with client settings for a `c1llm_` key. + +An inference API key only works for inference: listing models and running them. It doesn't work for egress, MCP servers, or the C1 API. + +## Before you begin with inference API keys + +Confirm the following before you start: + +| Requirement | Who provides it | +| :--- | :--- | +| **AI & API** in your C1 profile menu | Your C1 admin enables AI access management for your tenant | +| At least one model endpoint listed under **Inference API keys**, with the scopes you need. The Edge must have **Allow long-lived API keys** on; see [Set up an Edge for inference](/product/admin/edge-gateway-setup#optional-allow-long-lived-api-keys). | Your C1 admin grants access to an Edge Gateway that accepts inference API keys | +| Your Edge Gateway's inference endpoint, for example `https://-inference.edge.`. See [Find the Edge's connection values](/product/admin/edge-gateway-connect#find-the-edges-connection-details). | Your C1 admin | + +## Create an inference API key + +Create a key for one model endpoint, with only the scopes your tool needs. + + + +In C1, click your profile menu and click **AI & API**. + + +Click **Inference API keys**. + + +Click **Create inference API key**. + + +Enter a **Name** that identifies where you'll use the key, such as the tool or host name. + + +Select the **Model endpoint**. + + +Under **Granted scopes**, select the scopes the tool needs: + +- **Browse models** (`inference.models.read`) lists the models available through the endpoint. +- **Run models** (`inference.invoke`) sends inference requests. + + +Choose an **Expiration**. Pick the shortest period that works for the tool. + + +Click **Create**, and copy the key. + + + + + The Create inference API key dialog, with fields for Name, Model endpoint, Granted scopes (Browse models and Run models), and Expiration. + + +The key appears in your **Inference API keys** list. Keys start with `c1llm_`. Store the key in a secrets manager or your tool's secret storage; don't commit it to source control or paste it into chat. + +## Test your inference API key + +Run these commands in a terminal to confirm the key works before configuring a tool. First, load the key into your shell without printing it or saving it to your shell history: + + + + +```bash +read -rs "C1LLM_KEY?Paste inference API key: " && echo +``` + + + + +```bash +read -rsp "Paste inference API key: " C1LLM_KEY && echo +``` + + + + +Then set your Edge Gateway inference URL: + +```bash +EDGE_INFERENCE_URL=https:// +``` + +### List the models available to your key + +This request needs the **Browse models** scope: + +```bash +curl -s "$EDGE_INFERENCE_URL/v1/models" -H "Authorization: Bearer $C1LLM_KEY" +``` + +The response is an OpenAI-style list. Each entry's `id` is the model name to use in requests, and its `capabilities` show the request formats it accepts. + +### Run an inference request + +These requests need the **Run models** scope. Use the request format the model accepts. + + + + +```bash +curl -s "$EDGE_INFERENCE_URL/v1/messages" \ + -H "Authorization: Bearer $C1LLM_KEY" \ + -H "anthropic-version: 2023-06-01" \ + -H "content-type: application/json" \ + -d '{"model": "", "max_tokens": 50, "messages": [{"role": "user", "content": "Say hello"}]}' +``` + + + + +```bash +curl -s "$EDGE_INFERENCE_URL/v1/responses" \ + -H "Authorization: Bearer $C1LLM_KEY" \ + -H "content-type: application/json" \ + -d '{"model": "", "input": "Say hello", "store": false}' +``` + + + + +```bash +curl -s "$EDGE_INFERENCE_URL/v1/chat/completions" \ + -H "Authorization: Bearer $C1LLM_KEY" \ + -H "content-type: application/json" \ + -d '{"model": "", "messages": [{"role": "user", "content": "Say hello"}]}' +``` + + + + +A model's reply confirms the key, scopes, and model endpoint are working. An `invalid_request_error` with `"class":"compatibility"` means the model doesn't accept that request format; use a format listed in the model's `capabilities`. + +## Use an inference API key in your tools + +Send the key as a bearer token (`Authorization: Bearer`) to your Edge Gateway inference URL. Configure each tool with the variables it reads. + +### Use an inference API key with Claude Code + +Set `ANTHROPIC_AUTH_TOKEN`, which Claude Code sends as a bearer token. Don't use `ANTHROPIC_API_KEY`, which Claude Code sends in a different header. Set `ANTHROPIC_BASE_URL` to the inference URL without a `/v1` suffix. + +```bash +env -u ANTHROPIC_API_KEY \ + ANTHROPIC_BASE_URL="$EDGE_INFERENCE_URL" \ + ANTHROPIC_AUTH_TOKEN="$C1LLM_KEY" \ + claude --model -p "Reply with exactly: claude key ok" +``` + +The command prints `claude key ok`. For ongoing use, load the token from your secret storage when you launch the tool. Don't paste it into a shell profile or settings file. + +### Use an inference API key with OpenAI SDKs and tools + +Set `OPENAI_BASE_URL` to the inference URL with a `/v1` suffix, and `OPENAI_API_KEY` to the key: + +```bash +export OPENAI_BASE_URL="$EDGE_INFERENCE_URL/v1" +export OPENAI_API_KEY="$C1LLM_KEY" +``` + +OpenAI SDKs and tools that read these variables then send requests through Edge Gateway without code changes: + +```python +from openai import OpenAI + +client = OpenAI() # reads OPENAI_BASE_URL and OPENAI_API_KEY +response = client.responses.create(model="", input="Say hello", store=False) +print(response.output_text) +``` + +### Use an inference API key with the Anthropic SDK + +Pass the key as an auth token, so the SDK sends it as a bearer token: + +```python +import os +from anthropic import Anthropic + +client = Anthropic( + base_url="https://", + auth_token=os.environ["C1LLM_KEY"], # export C1LLM_KEY first +) +message = client.messages.create(model="", max_tokens=50, messages=[{"role": "user", "content": "Say hello"}]) +print(message.content[0].text) +``` + +## Revoke or rotate an inference API key + +Revoke a key as soon as you no longer need it or suspect it leaked. Revoke it in **AI & API** > **Inference API keys**, then confirm that new requests using the old key are rejected. + +To rotate a key, create a new key, update your tools to use it, confirm they work, then revoke the old key. + +## Troubleshoot inference API keys + +Edge Gateway's HTTP status code identifies most problems: + +| Response | Cause | What to do | +| :--- | :--- | :--- | +| `401` | The key is invalid, expired, or revoked, or it belongs to a different model endpoint than the URL you called. | Check that you copied the whole key and that the URL matches the key's model endpoint. Create a new key if it expired or was revoked. | +| `403` | The key is valid but lacks the scope for this request, or the Edge Gateway doesn't accept inference API keys. | Create a key with **Browse models** for listing and **Run models** for inference. If the scopes are correct, ask your C1 admin to check the Edge Gateway's settings. | +| `400` with `"class":"compatibility"` | The model doesn't accept the request format. | Use a request format listed in the model's `capabilities`. | +| `503` | Edge Gateway couldn't reach C1 to validate the key. | Retry after a short wait. | +| Claude Code reports an authentication error | Claude Code sent the key in the wrong header, or another credential overrode it. | Use `ANTHROPIC_AUTH_TOKEN`, not `ANTHROPIC_API_KEY`, and remove other Anthropic credentials from the environment. | + +## Frequently asked questions about inference API keys + + + + Yours. Edge Gateway attributes each request to the key's owner and records the key's ID in audit events. If your access to the model endpoint is removed, the key stops working even before it expires. + + + + No. Each key is bound to the model endpoint you selected when you created it. Create a separate key for each endpoint. + + + + No. Inference API keys only work for listing models and running inference. Use [C1 Multipass](/product/admin/connect-edge-gateway-multipass) for egress. + + + + Send a new request using the old key and confirm that authentication fails. Don't assume that revocation stops an already-running request. Contact the C1 Support team if new requests continue to succeed. + +