Skip to content

Fix/docs ai proxy apikey #1114

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
dengliming merged 2 commits into from
Apr 23, 2026
Merged

Fix/docs ai proxy apikey #1114

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
2c2a727
docs: update JDK requirement from 1.8 to 17+
Adonis-a233 Apr 23, 2026
4590a4b
docs: add API key management and X-API-KEY auth to ai-proxy plugin
Adonis-a233 Apr 23, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions docs/deployment/deployment-cluster.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,8 +13,8 @@ This article introduces how to deploy the `Shenyu` gateway in cluster environmen

### Environmental Preparation

* Two or more Gateway Boostrap servers, these servers must install JDK1.8+.
* A server for Gateway Admin, this server must install mysql/pgsql/h2 and JDK1.8+.
* Two or more Gateway Boostrap servers, these servers must install JDK17+.
* A server for Gateway Admin, this server must install mysql/pgsql/h2 and JDK17+.
* A server for nginx.

### Start Apache ShenYu Admin
Expand Down
2 changes: 1 addition & 1 deletion docs/deployment/deployment-quick.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ This article introduces how to quickly start the `Apache ShenYu` gateway in the

### Environmental preparation

* Install JDK1.8+ locally
* Install JDK17+ locally

### Start Apache ShenYu Bootstrap

Expand Down
46 changes: 46 additions & 0 deletions docs/plugin-center/ai/ai-proxy.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,3 +54,49 @@ curl --location --request POST 'http://localhost:9195/ai/proxy/v1/chat/completio
```

![](/img/shenyu/plugin/ai-proxy/ai-proxy-api.png)

## API Key Management

The aiProxy plugin supports managing proxy API keys through the ShenYu Admin interface. Each proxy API key is scoped to a specific Selector and maps to a real upstream API key.

### Admin Endpoints

Base path: `/selector/{selectorId}/ai-proxy-apikey`

| Method | Path | Description | Permission |
|--------|---------------------------------------------------------|------------------------------------|---------------------------------|
| POST | `/selector/{selectorId}/ai-proxy-apikey` | Create a proxy API key mapping | `system:aiProxyApiKey:add` |
| GET | `/selector/{selectorId}/ai-proxy-apikey` | List proxy API key mappings (paged) | `system:aiProxyApiKey:list` |
| PUT | `/selector/{selectorId}/ai-proxy-apikey/{id}` | Update a proxy API key mapping | `system:aiProxyApiKey:edit` |
| POST | `/selector/{selectorId}/ai-proxy-apikey/batchDelete` | Batch delete mappings | `system:aiProxyApiKey:delete` |
| POST | `/selector/{selectorId}/ai-proxy-apikey/batchEnabled` | Batch enable or disable mappings | `system:aiProxyApiKey:disable` |

### Query Parameters (GET)

| Parameter | Required | Description |
|----------------|----------|----------------------------------|
| `currentPage` | Yes | Page number |
| `pageSize` | Yes | Page size |
| `proxyApiKey` | No | Filter by proxy API key value |

## Proxy API Key Authentication

When `proxyEnabled` is set to `true` in the Selector configuration, the plugin enforces API key authentication on all incoming requests.

### Request Header

Clients must include the following header:

```
X-API-KEY: <proxy-api-key>
```

### Authentication Behavior

| Scenario | HTTP Status | Description |
|--------------------------------------------------|-------------------|------------------------------------------------------------------------------------------------------|
| `X-API-KEY` header present and valid | 200 | Request forwarded; real upstream API key substituted transparently |
| `X-API-KEY` header missing | 401 Unauthorized | Request rejected |
| `X-API-KEY` header present but invalid | 401 Unauthorized | Request rejected |

> **Note:** When proxy mode is enabled, the real upstream API key is never exposed to the client. The plugin resolves the mapping internally and substitutes the real key before forwarding the request to the LLM provider.
Loading