Skip to content

7.4 billion tokens per month. 34 free LLM providers. 635 free model endpoints. All behind one /v1 endpoint, plus any custom OpenAI-compatible endpoint. Smart routing, automatic failover, encrypted keys. Personal experimentation only.

TypeScript

fix(anthropic,gemini): client-profile keys authenticate /v1/messages and /v1beta (#1682)

tashdroid2af74e413fae
diff --git a/docs/en/api/01-rest-api.md b/docs/en/api/01-rest-api.md
index 81453927..85dca22e 100644
--- a/docs/en/api/01-rest-api.md
+++ b/docs/en/api/01-rest-api.md
@@ -197,6 +197,9 @@ curl "http://localhost:3001/v1beta/models/gemini-2.5-flash:generateContent" \
Gemini model names like `gemini-2.5-flash` resolve through the Gemini family map (Keys → Gemini model mapping) rather than the catalog directly, so they route to Auto or whichever catalog model each family is pinned to. Catalog ids work verbatim too.
+A client-profile key (`sk-cp-…`) authenticates the `/v1beta` generate/stream routes as
+well, with its enforced prompt injected ahead of `systemInstruction`.
+
`contents` text, inline data, function calls/responses, system instructions,
function declarations, structured JSON output, generation controls, and
thinking budgets translate into the same internal chat/fallback pipeline.
@@ -361,6 +364,10 @@ curl http://localhost:3001/v1/messages \
}'
```
+A **client-profile key** (`sk-cp-…`, see the dashboard's Profiles page) authenticates
+`/v1/messages` too: the profile's server-enforced system prompt is injected ahead of the
+caller's `system` turn, exactly as on `/v1/chat/completions`.
+
Claude model names map to your free pool on the **Keys → Anthropic** tab: each family (`default`, `opus`, `sonnet`, `haiku`) routes to `auto` (the router picks a free model) or a model you pin. `POST /v1/messages/count_tokens` and a content-negotiated `GET /v1/models` (Anthropic shape when `anthropic-version` is sent) are implemented too. Streaming, system prompts, tool use, and image input all translate across the same router as the OpenAI endpoints.
**Claude Code** — point it at your server and start it:
diff --git a/docs/en/api/CHANGELOG.md b/docs/en/api/CHANGELOG.md
index 9eebaeba..c80163b1 100644
--- a/docs/en/api/CHANGELOG.md
+++ b/docs/en/api/CHANGELOG.md
@@ -4,6 +4,10 @@
Doc revision history for `docs/api/`, seeded from API-relevant commits.
+## 2026-10-23
+
+- **fix(api): client-profile keys now authenticate `/v1/messages` and `/v1beta`** — the `sk-cp-*` keys from #411 were accepted only by `/v1/chat/completions` and `/v1/responses`; the Anthropic and Gemini surfaces still compared the unified key alone, so a downstream app speaking the Claude or Gemini wire format got `401` with its own profile key. Both routes now resolve through `resolveAuth`: profile keys carry their server-enforced system prompt (injected first, after compression on `/v1/messages`, ahead of `systemInstruction` on `/v1beta` — same ordering contract), and a disabled profile fails like a bad key. Source: `server/src/routes/anthropic.ts`, `server/src/routes/gemini.ts`.
+
## 2026-10-20
- **docs(api): document `GET /v1/usage`** — the endpoint shipped with #1600 and gained a per-key breakdown in #1614 but was never in `01-rest-api.md`. Added a Usage API section: response shape (`month`, `resetsAt`, `requests`, `tokens`, `byPlatform[]`, `byKey[]` with `requestCap`/`tokenCap`, `null` = unlimited), unified-key-only auth (`403` for client profiles), deleted keys surfacing under platform `removed`, and the ledger-not-clamped-at-cap semantics that match `429 quota_exceeded`. Source: `server/src/routes/proxy.ts` (`GET /v1/usage` handler).
diff --git a/docs/zh-cn/api/01-rest-api.md b/docs/zh-cn/api/01-rest-api.md
index a038edeb..ce9c185b 100644
--- a/docs/zh-cn/api/01-rest-api.md
+++ b/docs/zh-cn/api/01-rest-api.md
@@ -175,6 +175,8 @@ curl "http://localhost:3001/v1beta/models/gemini-2.5-flash:generateContent" \
像 `gemini-2.5-flash` 这样的 Gemini 模型名,是通过 Gemini 系列映射(密钥 → Gemini 模型映射)解析的,而不是直接查目录,所以它们会路由到 Auto,或者路由到你为每个系列固定的那个目录模型。直接写目录里的 id 也一样能用。
+客户端档案密钥(`sk-cp-…`)同样可以通过 `/v1beta` 的生成/流式路由鉴权,其强制提示词会注入在 `systemInstruction` 之前。
+
`contents` 里的文本、内联数据、函数调用与响应、系统指令、函数声明、结构化 JSON 输出、生成控制参数和思考额度,都会翻译进同一套内部的聊天与回退流程。Bearer 认证同样可用。Gemini 的 `?key=` 查询参数只在 `/v1beta` 下被接受;建议优先用请求头,因为写在 URL 里的凭据会泄漏到历史记录和日志中。
## Ollama 模拟
@@ -277,6 +279,8 @@ curl http://localhost:3001/v1/messages \
}'
```
+**客户端档案密钥**(`sk-cp-…`,见仪表盘的档案页)同样可以通过 `/v1/messages` 鉴权:档案的服务端强制系统提示词会注入在调用方 `system` 轮之前,与 `/v1/chat/completions` 上的行为完全一致。
+
Claude 的模型名在 **密钥 → Anthropic** 标签页里映射到你的免费池:每个系列(`default`、`opus`、`sonnet`、`haiku`)可以路由到 `auto`(由路由器挑一个免费模型),也可以固定到你指定的模型。`POST /v1/messages/count_tokens` 和一个按内容协商的 `GET /v1/models`(发送了 `anthropic-version` 时返回 Anthropic 的结构)也都实现了。流式、系统提示词、工具使用和图像输入,都经由和 OpenAI 端点相同的那套路由翻译。
**Claude Code** —— 把它指向你的服务器再启动:
diff --git a/docs/zh-cn/api/CHANGELOG.md b/docs/zh-cn/api/CHANGELOG.md
index 6d28dd5a..91014aef 100644
--- a/docs/zh-cn/api/CHANGELOG.md
+++ b/docs/zh-cn/api/CHANGELOG.md
@@ -4,6 +4,10 @@
`docs/api/` 的文档修订历史。最近的在前。
+## 2026-10-23
+
+- **fix(api):客户端档案密钥现在可通过 `/v1/messages` 与 `/v1beta` 鉴权** —— #411 的 `sk-cp-*` 密钥此前只被 `/v1/chat/completions` 与 `/v1/responses` 接受;Anthropic 与 Gemini 路由仍只比对统一密钥,导致下游应用拿着自己的档案密钥得到 `401`。两条路由现在都经由 `resolveAuth` 解析:档案密钥携带其服务端强制系统提示词(最先注入——`/v1/messages` 在压缩之后、`/v1beta` 在 `systemInstruction` 之前——排序契约一致),被禁用的档案按坏密钥处理。来源:`server/src/routes/anthropic.ts`、`server/src/routes/gemini.ts`。
+
## 2026-08-23 —— 文档重组
- **36850e8** `docs(api): fold API guide into api domain` — `docs/api.md` → `docs/api/01-rest-api.md`,补 `OVERVIEW.md` + `CHANGELOG.md` 脚手架。(经 #979 合入)
diff --git a/server/src/__tests__/routes/client-profiles.test.ts b/server/src/__tests__/routes/client-profiles.test.ts
index 15566b7d..8356b34e 100644
--- a/server/src/__tests__/routes/client-profiles.test.ts
+++ b/server/src/__tests__/routes/client-profiles.test.ts
@@ -237,4 +237,75 @@ describe('client profiles (#411)', () => {
expect(sent[1]).toMatchObject({ role: 'system', content: 'caller instructions' });
});
});
+
+ describe('the Anthropic surface (/v1/messages) honors profile keys', () => {
+ const anthropicBody = {
+ model: 'auto',
+ max_tokens: 64,
+ system: 'caller instructions',
+ messages: [{ role: 'user', content: 'hi' }],
+ };
+
+ it('accepts a profile key on x-api-key and injects the enforced prompt first', async () => {
+ const created = await createProfile('anthropic-bot', 'ENFORCED PROMPT');
+ const { status } = await request(app, 'POST', '/v1/messages', {
+ token: created.key, body: anthropicBody,
+ });
+ expect(status).toBe(200);
+ const sent = seenMessages[0];
+ // Same ordering contract as /v1/chat/completions: enforced first, the
+ // caller's system turn survives after it.
+ expect(sent[0]).toMatchObject({ role: 'system', content: 'ENFORCED PROMPT' });
+ expect(sent.some(m => m.role === 'system' && m.content === 'caller instructions')).toBe(true);
+ });
+
+ it('the unified key injects nothing on /v1/messages', async () => {
+ const { status } = await request(app, 'POST', '/v1/messages', {
+ token: unifiedKey, body: anthropicBody,
+ });
+ expect(status).toBe(200);
+ expect(seenMessages[0][0]).toMatchObject({ role: 'system', content: 'caller instructions' });
+ });
+
+ it('a disabled profile key gets 401 on /v1/messages too', async () => {
+ const created = await createProfile('anthropic-off', 'x');
+ await request(app, 'PATCH', `/api/client-profiles/${created.id}`, {
+ token: dashToken, body: { enabled: false },
+ });
+ const { status } = await request(app, 'POST', '/v1/messages', {
+ token: created.key, body: anthropicBody,
+ });
+ expect(status).toBe(401);
+ });
+ });
+
+ describe('the Gemini surface (/v1beta) honors profile keys', () => {
+ const geminiBody = {
+ contents: [{ role: 'user', parts: [{ text: 'hi' }] }],
+ systemInstruction: { parts: [{ text: 'caller instructions' }] },
+ };
+ const geminiPath = '/v1beta/models/gemini-2.5-flash:generateContent';
+
+ it('accepts a profile key and injects the enforced prompt first', async () => {
+ const created = await createProfile('gemini-bot', 'ENFORCED PROMPT');
+ const { status } = await request(app, 'POST', geminiPath, {
+ token: created.key, body: geminiBody,
+ });
+ expect(status).toBe(200);
+ const sent = seenMessages[0];
+ expect(sent[0]).toMatchObject({ role: 'system', content: 'ENFORCED PROMPT' });
+ expect(sent.some(m => m.role === 'system' && m.content === 'caller instructions')).toBe(true);
+ });
+
+ it('a disabled profile key gets 401 on /v1beta too', async () => {
+ const created = await createProfile('gemini-off', 'x');
+ await request(app, 'PATCH', `/api/client-profiles/${created.id}`, {
+ token: dashToken, body: { enabled: false },
+ });
+ const { status } = await request(app, 'POST', geminiPath, {
+ token: created.key, body: geminiBody,
+ });
+ expect(status).toBe(401);
+ });
+ });
});
diff --git a/server/src/routes/anthropic.ts b/server/src/routes/anthropic.ts
index 6cfc47e1..a3538d34 100644
--- a/server/src/routes/anthropic.ts
+++ b/server/src/routes/anthropic.ts
@@ -10,7 +10,8 @@ import type {
ChatContentBlock,
} from '@freellmapi/shared/types.js';
import { routeRequest, resolveModelGroupCandidates, resolveRoutingChain, resolveStickyPreference, routingReserveTokens, failureAttributionFor, type RouteResult, type ResolvedChain, type ChainRow } from '../services/router.js';
-import { getSetting, getUnifiedApiKey } from '../db/index.js';
+import { getSetting } from '../db/index.js';
+import { resolveAuth, prependSystemPrompt, type ResolvedAuth } from '../lib/system-prompt.js';
import { contentToString, estimateInputTokens } from '../lib/content.js';
import { routeOutputBudget } from '../lib/output-cap.js';
import { resolveTaskType } from '../lib/task-type.js';
@@ -21,7 +22,7 @@ import { sanitizeProviderErrorMessage } from '../lib/error-redaction.js';
import { convertDocumentBlock, documentRejectionMessage } from '../lib/anthropic-documents.js';
import { isClientAbortError, newClientAbortError, newHedgeAbortError, isUpstreamClassificationOutput } from '../lib/error-classify.js';
import { logRequest } from '../lib/request-log.js';
-import { extractApiToken, timingSafeStringEqual, getStickyModel, setStickyModel } from './proxy.js';
+import { extractApiToken, getStickyModel, setStickyModel } from './proxy.js';
import { runFallbackLoop, newFallbackState, fallbackRoutingTokens, recordUpstreamSuccess, type ExhaustionBody, setFallbackHeaders, setExhaustionHeaders, type AttemptRecord, type FallbackState, REASONING_HOLD_MAX_MS } from '../lib/fallback-loop.js';
import { routedViaValue } from '../lib/header-value.js';
import { startStreamKeepalive, streamKeepaliveMs } from '../lib/stream-keepalive.js';
@@ -205,14 +206,17 @@ function newMessageId(): string {
}
// ── Auth (shared with the OpenAI route) ─────────────────────────────────────
-function authenticate(req: Request, res: Response): boolean {
- const token = extractApiToken(req);
- const unifiedKey = getUnifiedApiKey();
- if (!token || !timingSafeStringEqual(token, unifiedKey)) {
+// Resolves both credential kinds (#411): the unified key behaves exactly as
+// before; a client-profile key (sk-cp-*) authenticates inference only and
+// carries its server-enforced system prompt. A disabled/unknown profile fails
+// like a bad key so a revoked client learns nothing extra.
+function authenticate(req: Request, res: Response): ResolvedAuth | null {
+ const auth = resolveAuth(extractApiToken(req));
+ if (!auth) {
sendError(res, 401, 'authentication_error', 'Invalid API key');
- return false;
+ return null;
}
- return true;
+ return auth;
}
// ── Request translation: Anthropic → internal (OpenAI-shaped) ───────────────
@@ -461,7 +465,8 @@ anthropicRouter.post('/messages', async (req: Request, res: Response) => {
export async function handleMessages(req: Request, res: Response): Promise<void> {
const start = Date.now();
- if (!authenticate(req, res)) return;
+ const auth = authenticate(req, res);
+ if (!auth) return;
const parsed = messagesSchema.safeParse(req.body);
if (!parsed.success) {
@@ -520,6 +525,12 @@ export async function handleMessages(req: Request, res: Response): Promise<void>
messages = compressionResult.messages;
res.setHeader('X-FreeLLM-Compress', formatCompressionHeader(compressionResult));
+ // Server-enforced system prompt (#411): injected AFTER compression so it is
+ // never compressed away, and FIRST in the list so a caller-supplied system
+ // turn follows it and cannot override it. Neutral no-op for the unified key
+ // and for profiles without a prompt.
+ messages = prependSystemPrompt(messages, auth.systemPrompt);
+
const estimatedInputTokens = estimateInputTokens(messages, tools);
const imageCount = messages.reduce((n, m) =>
n + (Array.isArray(m.content) ? m.content.filter(b => (b as any)?.type === 'image_url').length : 0), 0);
diff --git a/server/src/routes/gemini.ts b/server/src/routes/gemini.ts
index 4b9414ce..e9b4f568 100644
--- a/server/src/routes/gemini.ts
+++ b/server/src/routes/gemini.ts
@@ -1,9 +1,9 @@
import { Router } from 'express';
import type { Request, Response } from 'express';
import { z } from 'zod';
-import { getUnifiedApiKey } from '../db/index.js';
import { buildModelListing, type NormalizedModel } from '../services/model-listing.js';
-import { extractApiToken, timingSafeStringEqual } from './proxy.js';
+import { extractApiToken } from './proxy.js';
+import { resolveAuth, prependSystemPrompt, type ResolvedAuth } from '../lib/system-prompt.js';
import { runInboundChat, type InboundChatWire } from '../lib/inbound-chat.js';
import {
effortFromGeminiThinking,
@@ -44,7 +44,10 @@ function sendError(res: Response, status: number, message: string, code = 'INVAL
});
}
-function authenticate(req: Request, res: Response): boolean {
+// Resolves both credential kinds (#411): unified key as before; a
+// client-profile key (sk-cp-*) authenticates inference only and carries its
+// server-enforced system prompt (injected by handleGenerate below).
+function authenticate(req: Request, res: Response): ResolvedAuth | null {
const queryKey = typeof req.query.key === 'string' ? req.query.key.trim() : '';
if (queryKey) {
// Query credentials are a Gemini compatibility escape hatch and are
@@ -52,12 +55,12 @@ function authenticate(req: Request, res: Response): boolean {
// shell history, reverse-proxy logs, and referrer telemetry.
console.warn('[Gemini] API key supplied in ?key=; prefer x-goog-api-key to avoid URL leakage');
}
- const token = extractApiToken(req) ?? queryKey;
- if (!token || !timingSafeStringEqual(token, getUnifiedApiKey())) {
+ const auth = resolveAuth(extractApiToken(req) ?? queryKey);
+ if (!auth) {
sendError(res, 401, 'Invalid API key', 'UNAUTHENTICATED');
- return false;
+ return null;
}
- return true;
+ return auth;
}
function modelShape(model: NormalizedModel | null, autoContextWindow: number | null, id = 'auto') {
@@ -185,7 +188,8 @@ function streamWire(altSse: boolean): InboundChatWire {
}
async function handleGenerate(req: Request, res: Response, stream: boolean): Promise<void> {
- if (!authenticate(req, res)) return;
+ const auth = authenticate(req, res);
+ if (!auth) return;
const body = parseGenerateBody(req, res);
if (!body) return;
const generation = body.generationConfig;
@@ -198,7 +202,10 @@ async function handleGenerate(req: Request, res: Response, stream: boolean): Pro
const tools = geminiToolsToChatTools(body.tools);
await runInboundChat(req, res, {
model: resolveGeminiModel(model),
- messages: geminiContentsToMessages(body),
+ // Server-enforced system prompt (#411): enforced prompt FIRST so the
+ // caller's systemInstruction follows it and cannot override it. Neutral
+ // no-op for the unified key and for profiles without a prompt.
+ messages: prependSystemPrompt(geminiContentsToMessages(body), auth.systemPrompt),
stream,
// Gemini CLI never sends maxOutputTokens; the shared 1024-token default
// would truncate every response, so match Gemini's own model default.