pangolin_mirror/docs-v2
1
0
Fork 0
mirror of https://github.com/fosrl/docs-v2.git synced 2026-08-30 18:51:29 +02:00
Code Issues Packages Projects Releases Wiki Activity

add remote headers

Browse Source
This commit is contained in:
miloschwartz
2026-08-20 17:32:01 -04:00
parent 317400da8b
commit 3ad459c7ae
7 changed files with 130 additions and 23 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
docs.json
View File

@@ -189,6 +189,7 @@
"icon": "robot",
"pages": [
"manage/ai/overview",
"manage/ai/virtual-api-keys",
{
"group": "Providers",
"pages": [

12
manage/access-control/forwarded-headers.mdx
View File

@@ -2,7 +2,7 @@
title: "Forwarded Headers"
description: "Learn how Pangolin forwards user identity information to your backend applications through HTTP headers"
---
Pangolin can forward user identity information to your backend applications through custom HTTP headers. This allows your applications to receive user details directly from the request headers, enabling integration with Pangolin's authentication system.
Pangolin can forward user identity information to your backend applications through custom HTTP headers. This allows your applications to receive user details directly from the request headers, enabling integration with Pangolin's authentication system. [AI Gateway](/manage/ai/overview) resources send the same headers to the upstream provider when the caller is a known user. See [Identity Headers](/manage/ai/providers/configuration#identity-headers).
<Info>
Forwarded headers are only available when using authentication methods that provide user identity information.
@@ -52,3 +52,13 @@ These authentication methods do not provide user identity information:
No user identity - only access control.
</Card>
</CardGroup>
## AI Gateway
[AI Gateway](/manage/ai/overview) resources forward the same `Remote-User`, `Remote-Email`, `Remote-Name`, and `Remote-Role` headers to the upstream model API when Pangolin knows the user:
- A public resource called with an [identity key](/manage/ai/virtual-api-keys#identity-keys)
- A public resource called with a [manual key](/manage/ai/virtual-api-keys#manual-keys) attributed to a user
- A private AI Gateway resource called from a connected [Pangolin client](/manage/clients/install-client)
An unattributed manual key authenticates without sending these headers. Details are in [Identity Headers](/manage/ai/providers/configuration#identity-headers).

33
manage/ai/overview.mdx
View File

@@ -3,47 +3,40 @@ title: "AI Gateway Overview"
description: "Route coding agents and AI clients through Pangolin with centralized providers and keys"
---
An AI Gateway resource is a normal Pangolin resource that proxies requests to one or more upstream AI providers (OpenAI, Anthropic, Google Gemini, Bedrock, Vertex AI, or a custom endpoint). Point a client at the resource's URL instead of the provider's, and Pangolin handles auth, access control, and logging in front of it.
## How it fits together
## How It Fits Together
- **[Providers](/manage/ai/providers/overview)** are configured once per organization - the upstream URL, API key, and capabilities for OpenAI, Anthropic, etc.
- **Resources** (type `AI Gateway`) attach one or more of those providers and get a normal Pangolin domain.
- **Keys** are what clients authenticate to the resource with. Public resources check them; private resources don't, since only devices on the Pangolin network can reach them at all.
- **[Virtual API Keys](/manage/ai/virtual-api-keys)** are what clients send to a **public** AI Gateway resource. Private resources are reached through the Pangolin network, so the gateway does not check a key.
- The **[Model Catalog](/manage/ai/model-catalog)** is the known-model list and token pricing used by [model routing](/manage/ai/providers/model-routing) and budgets.
A resource only understands the API format(s) its attached providers support. An Anthropic provider makes the resource speak the Anthropic Messages API; an OpenAI provider makes it speak Chat Completions/Responses; a Gemini provider makes it speak Gemini's `generateContent` API. Attach whichever providers match the clients you plan to connect. See [AI Providers](/manage/ai/providers/overview) for per-type setup and [Provider Configuration](/manage/ai/providers/configuration) for capabilities, auth, and model lists.
## 1. Add a provider
## 1. Add a Provider
Create an org-level provider so the gateway has an upstream to call. Sidebar → **AI Gateway** → **Providers** → **Create**, or follow the [AI Providers](/manage/ai/providers/overview) guide. Pick a type, paste in its API key, and save. You can add as many as you need.
## 2. Create a resource
## 2. Create a Resource
Resources → **Create** → set **Type** to **AI Gateway**, pick a domain, and attach the provider(s) from step 1. You can also attach providers to an existing resource later from its **AI Gateway** settings tab.
## 3. Get a key
## 3. Get a Key
How a client authenticates depends on whether the resource is public or private.
How a client authenticates depends on whether the resource is public or private. See [Virtual API Keys](/manage/ai/virtual-api-keys) for identity vs manual keys, always-on auth, and where to copy a key.
### Public resources
### Public Resources
Reachable from anywhere, so the gateway checks an API key. Find yours in either place:
Reachable from anywhere, so the gateway checks a virtual API key. Copy yours from the resource URL after login, the Resource Launcher more-info panel, or `https://app.pangolin.net/<org-id>/keys` (use your self-hosted dashboard URL in place of `app.pangolin.net` if you self-host).
- Your org's **Your API Keys** page (top-level nav)
- The resource's **API Keys** panel in the Resource Launcher
### Private Resources
Both show your personal **Identity Key** and any other keys attributed to you.
Only reachable from devices connected to your Pangolin network, so the gateway does not check a key. Instead, the machine running the client needs the [Pangolin client](/manage/clients/install-client) installed and connected.
### Private resources
You still have to put *something* in the client's key field. Most AI clients refuse to start with a missing key, so use the literal string `none`. Deleting the field usually breaks things. Claude Code, for instance, silently falls back to your regular Anthropic account if `apiKeyHelper` is missing, and OpenCode errors out with `OpenAI API key is missing`.
Only reachable from devices connected to your Pangolin network, so no key is checked. Instead, the machine running the client needs the [Pangolin client](/manage/clients/install-client) installed and connected.
You still have to put *something* in the client's key field. Most AI clients refuse to start with no key set at all, so use the literal string `none`. Deleting the field usually breaks things - Claude Code, for instance, silently falls back to your regular Anthropic account if `apiKeyHelper` is missing, and OpenCode errors out with `OpenAI API key is missing`.
## 4. Connect a client
## 4. Connect a Client
Every resource's Keys page has ready-to-copy setup for common clients, and `pangolin configure <client>` can write the config for you. Full instructions per client:
@@ -60,7 +53,7 @@ There are also guides for pointing other tools at a Pangolin AI Gateway resource
- [Claude Desktop](/manage/ai/configure-ai-clients/claude-desktop)
- [OpenClaw](/manage/ai/configure-ai-clients/openclaw)
## Supported providers
## Supported Providers
Each type has its own configuration guide. Capabilities (which API formats a provider speaks) are explained in [Provider Configuration](/manage/ai/providers/configuration#capabilities).

21
manage/ai/providers/configuration.mdx
View File

@@ -66,3 +66,24 @@ On **Network** you can also set:
- **Custom headers** sent on every request to this provider (`Header-Name: value`, one per line)
- **Skip TLS verification** for the upstream connection
### Identity Headers
When Pangolin knows which user made the request, it forwards that identity to the upstream on every call:
| Header | Value |
|---|---|
| `Remote-User` | Username |
| `Remote-Email` | Email, when set |
| `Remote-Name` | Display name, when set |
| `Remote-Role` | Org role names, when the user has roles |
The user is known when:
- A public resource is called with an [identity key](/manage/ai/virtual-api-keys#identity-keys)
- A public resource is called with a [manual key](/manage/ai/virtual-api-keys#manual-keys) attributed to a user
- A private AI Gateway resource is called from a connected [Pangolin client](/manage/clients/install-client), and that client maps to a user
An unattributed manual key still authenticates, but these headers are omitted. Empty values are omitted rather than sent blank.
These are the same names as [Forwarded Headers](/manage/access-control/forwarded-headers) on HTTPS resources. A Custom upstream such as [Bifrost](/manage/ai/providers/custom/bifrost) can use them for downstream access control. They are sent in addition to any custom headers you configure on the provider.

4
manage/ai/providers/custom/bifrost.mdx
View File

@@ -22,4 +22,6 @@ See [Capabilities](/manage/ai/providers/configuration#capabilities) for the full
7. Save. On the **Network** tab, add a target: the Bifrost host, port `8080`, method HTTP.
8. Attach the provider to an [AI Gateway resource](/manage/ai/overview).
Then point a client at that resource: [Codex](/manage/ai/configure-ai-clients/codex), [OpenCode](/manage/ai/configure-ai-clients/opencode), or [Open WebUI](/manage/ai/configure-ai-clients/open-webui). Clients still call the Pangolin resource. Bifrost only sees the request after Pangolin has authenticated it.
Then point a client at that resource: [Codex](/manage/ai/configure-ai-clients/codex), [OpenCode](/manage/ai/configure-ai-clients/opencode), or [Open WebUI](/manage/ai/configure-ai-clients/open-webui). Clients still call the Pangolin resource. Bifrost only sees the request after Pangolin has authenticated it.
When the caller is a known user, Pangolin forwards [`Remote-User`, `Remote-Email`, `Remote-Name`, and `Remote-Role`](/manage/ai/providers/configuration#identity-headers). Use those in Bifrost (or any Custom upstream) for downstream access control. An unattributed [manual key](/manage/ai/virtual-api-keys#manual-keys) authenticates without sending them.

80
manage/ai/virtual-api-keys.mdx Normal file
View File

@@ -0,0 +1,80 @@
---
title: "Virtual API Keys"
description: "Authenticate AI clients to public AI Gateway resources without sharing upstream provider keys"
---
A virtual API key is a Pangolin credential that AI clients send to a public AI Gateway resource. Users retrieve their **identity key** by logging in with their existing Pangolin account or [identity provider](/manage/identity-providers/add-an-idp). That key is bound to their Pangolin identity, so calls are attributed to them for auditing, tracking, and access enforcement. When the user is known, Pangolin also forwards that identity upstream as [`Remote-*` headers](/manage/ai/providers/configuration#identity-headers).
The real OpenAI, Anthropic, Gemini, or other provider key stays on the [provider](/manage/ai/providers/overview). Pangolin checks the virtual key, then forwards the request with the upstream secret.
These keys are what coding agents put in their API key field. They are not [Integration API](/manage/integration-api) organization or root keys.
## Why Virtual API Keys
Agents and SDKs expect an API key. Virtual keys let many people and services call the gateway while the org keeps a single upstream provider key.
- Revoke or rotate one person or agent's access without rotating the provider key
- Attribute usage to a user or a named key
- Use the same Pangolin credential in clients that send `Authorization: Bearer`, `x-api-key`, or `x-goog-api-key`
Pangolin accepts the virtual key in those headers and strips it before the upstream call. Keys look like `pangolin-key-<id>.<secret>`.
Logging into Pangolin in a browser is how you **retrieve** a key. Model calls still need the virtual key in the request. A dashboard session cookie cannot proxy through the gateway.
## Public Resources Only
Virtual keys apply to **public** AI Gateway resources. [Private resources](/manage/resources/understanding-resources) are reached through the [Pangolin client](/manage/clients/install-client), so the gateway does not check a key. Clients still need a placeholder in the key field; use the literal string `none`. Deleting the field usually breaks the client.
## Authentication Is Always On
Public AI Gateway resources always require authentication. Unlike [HTTPS public resources](/manage/resources/public/authentication), you cannot turn Platform SSO off.
Assign [users and roles](/manage/access-control/create-user) on the resource the same way you would for a public HTTPS resource. Those grants control who can use an **identity key**.
HTTPS resources can add PIN, passcode, header auth, shareable links, or email OTP for browser access. AI clients authenticate programmatically, so the gateway uses virtual API keys instead of those methods.
## Identity Keys vs Manual Keys
Both kinds are `pangolin-key-…` secrets. They differ in how access is granted.
### Identity Keys
Every organization user already has an identity key. It is unique to their account and authenticates them as that user.
Access follows the resource's **Users** and **Roles**, the same way a public HTTPS resource does. Grant the user or their role on the AI Gateway resource, or their identity key cannot call it.
Admins do not mint identity keys; they already exist. To send them out, see [Email Keys to Users](#email-keys-to-users).
### Manual Keys
Admins create manual keys at **AI Gateway → Virtual API Keys → Virtual Keys**. Scope a key to selected public AI gateways, or to every public AI gateway in the org.
Creating the key immediately grants access to those resources, regardless of the users and roles set on the resource. Use this for services, CI, and shared agents that should not depend on a person's resource grants.
You can optionally associate a user. That association is for usage tracking and so the key appears on that user's keys page. It does not change which resources the key can call.
## Where to Get a Key
Your identity key and any manual keys attributed to you are available in three places:
1. Visit the public resource URL in a browser and log in with your Pangolin identity. After login, Pangolin shows the key.
2. Open the Resource Launcher, select the resource, and use the more-info side panel.
3. Go to `https://app.pangolin.net/<org-id>/keys` (the org **Your API Keys** page). On self-hosted Pangolin, use the same path on your dashboard URL, for example `https://pangolin.example.com/<org-id>/keys`.
See [Organization ID](/manage/organizations/org-id) if you need to look up `<org-id>`.
Put that key in the AI client. Visiting the resource in a browser only reveals the key; it does not authenticate the agent's requests.
## Email Keys to Users
Admins can email keys so users do not have to find the dashboard page themselves. The message includes the secret and public AI gateway URLs they can call.
### Email Identity Keys
**AI Gateway → Virtual API Keys → Identity Keys → Email Identity Keys.** Send every organization member their identity key, or pick specific users and roles. Recipients without an account email are skipped.
### Email Manual Keys
When you create or edit a manual key, enable **Email key upon generation** (or **Email this key**). Send it to the associated user and to extra addresses you add.
Self-hosted Pangolin needs [SMTP](/self-host/advanced/config-file#email-configuration) configured before either flow can send mail.

2
snippets/ai-gateway-key.mdx
View File

@@ -3,7 +3,7 @@
Wherever these instructions show `<key>`, what you put there depends on the resource type:
- **Public resource** - reachable from anywhere, so the gateway checks your API key. Use the key from the resource's Keys page or your personal org API key which can be retrieved from the dashboard.
- **Public resource** - reachable from anywhere, so the gateway checks a [virtual API key](/manage/ai/virtual-api-keys). Copy it from the resource URL after login, the Resource Launcher more-info panel, or `https://app.pangolin.net/<org-id>/keys` (use your self-hosted dashboard URL in place of `app.pangolin.net` if you self-host).
- **Private resource** - only reachable from devices connected to your Pangolin network, so no key is checked. You must have the [Pangolin client](/manage/clients/install-client) installed and connected. Use the literal string `none` as the key.
Don't delete the key field for private resources. Most clients refuse to start without *some* key set, so they need an inert placeholder rather than a missing one.