You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 63edd4b
Browse filesBrowse the repository at this point in the historyBrowse files
docs: point remote catalog fetch at the data-plane /v1/catalog route
The Codex integration guide told operators to fetch the catalog with
OPENCODEX_ADMIN_AUTH_TOKEN against /api/catalog — which is exactly the
least-privilege problem #809 describes. English and all seven locales now use
an ordinary data-plane key against /v1/catalog, and state that a data key
admitted there gains nothing on the management plane.
@@ -274,6 +274,8 @@ Vous pouvez également définir ou modifier ce nom dans l'API de gestion — `PO
274
274
`PUT /api/custom-models/<id>` avec une chaîne `displayName` — et dans le tableau de bord web. Le caractère `/`
275
275
est refusé, car il entrerait en collision avec le séparateur des identifiants de routage.
276
276
277
+
`GET /v1/catalog` existe pour que la lecture d'une liste de modèles ne coûte pas un jeton d'administration. La route est en lecture seule (`GET` et `HEAD`), accepte `x-opencodex-api-key`, un jeton bearer ou `x-api-key`, et renvoie exactement les mêmes octets que la route de gestion. Les réponses portent un `ETag` fort — renvoyez-le dans `If-None-Match` pour revalider et obtenir un `304` — et `Cache-Control: private, no-cache`. Une clé du plan de données admise ici n'obtient **rien** sur le plan de gestion : `/api/catalog` et toutes les routes `/api/*` exigent toujours le jeton d'administration ou une session du tableau de bord.
278
+
277
279
Le nom d'affichage sert **uniquement à l'affichage et reste stable entre les régénérations**. À chaque `ocx sync`
278
280
et à chaque actualisation du catalogue, opencodex reconstruit les entrées routées depuis `config.json`, y compris
279
281
`customModels` ; le nom configuré est donc réappliqué au lieu de revenir à l'identifiant de routage. Un service
또한 management API(`POST /api/custom-models`, `PUT /api/custom-models/<id>`의 `displayName` string)와 웹 대시보드에서도 설정하거나 수정할 수 있습니다. `/`는 routed-slug separator와 충돌하므로 거부됩니다.
170
170
171
+
`GET /v1/catalog`은 모델 목록을 읽는 데 관리자 토큰이 필요하지 않도록 존재합니다. 읽기 전용(`GET`, `HEAD`)이며 `x-opencodex-api-key`, bearer 토큰, `x-api-key`를 허용하고 관리 라우트와 완전히 동일한 바이트를 제공합니다. 응답에는 강한 `ETag`가 포함되므로 `If-None-Match`로 다시 보내면 전체 문서 대신 `304`를 받고, `Cache-Control: private, no-cache`가 함께 설정됩니다. 여기서 허용된 데이터 플레인 키는 관리 플레인에서 **아무 권한도** 얻지 못합니다. `/api/catalog`을 비롯한 모든 `/api/*` 라우트는 여전히 관리자 토큰이나 대시보드 세션을 요구합니다.
172
+
171
173
표시 이름은 **표시 전용이며 재생성 사이에서도 안정적**입니다. 모든 `ocx sync`와 catalog refresh는 `config.json`(`customModels` 포함)에서 routed entry를 다시 계산하므로, 설정된 이름이 라우팅 slug로 되돌아가지 않고 다시 적용됩니다. 관리형 service restart도 proxy가 bind된 직후 이 sync를 다시 시도합니다. 예를 들어 offline login 중이라 이 best-effort boot sync가 실패하면, 이전에 저장된 catalog는 유지되고 다음에 성공한 `ocx sync`가 설정된 이름을 다시 적용합니다. 진짜 upstream native name(예: `gpt-5.6-sol` → "GPT-5.6-Sol")은 고정된 upstream snapshot에서 오며, custom display name으로 덮어쓰지 않습니다.
Copy file name to clipboardExpand all lines: docs-site/src/content/docs/reference/management-api.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -152,7 +152,7 @@ first and submit the returned digest. Prefer quarantine when recovery may be nee
152
152
153
153
| Method and path | Purpose | Notable errors |
154
154
| --- | --- | --- |
155
-
|`GET /api/catalog`| Return the installed Codex catalog document | 404 catalog not found |
155
+
|`GET /api/catalog`| Return the installed Codex catalog document. Remote clients should prefer the data-plane `GET /v1/catalog`, which needs no admin token.| 404 catalog not found |
156
156
|`GET /api/models`| Return the dashboard/CLI model rows |`catalog_busy` when gathering is saturated |
157
157
|`GET /api/client-config?client=...`| Build a read-only client config for any supported file integration | 400 unsupported client; 503 catalog unavailable |
158
158
|`PUT /api/disabled-models`| Replace the shared disabled-model list | 400 invalid JSON |
@@ -264,6 +264,8 @@ Display name можно задать или отредактировать и ч
264
264
(`POST /api/custom-models`, `PUT /api/custom-models/<id>` с полем `displayName`) и через
265
265
веб-дашборд. Символ `/` запрещён, потому что он столкнулся бы с разделителем routed-slug.
266
266
267
+
`GET /v1/catalog` существует для того, чтобы чтение списка моделей не требовало админского токена. Маршрут только для чтения (`GET` и `HEAD`), принимает `x-opencodex-api-key`, bearer-токен или `x-api-key` и отдаёт в точности те же байты, что и управляющий маршрут. Ответы содержат строгий `ETag` — верните его в `If-None-Match`, чтобы повторно проверить и получить `304` вместо полного документа — и `Cache-Control: private, no-cache`. Ключ плоскости данных, допущенный здесь, **не получает ничего** на плоскости управления: `/api/catalog` и все маршруты `/api/*` по-прежнему требуют админский токен или сессию панели.
268
+
267
269
Display name — это **только отображение, и оно устойчиво к перегенерации**. Каждый `ocx sync` и
268
270
каждое обновление каталога заново выводят маршрутизируемые записи из `config.json`
269
271
(включая `customModels`), поэтому настроенное имя накладывается снова и не «дрейфует» обратно к
@@ -307,6 +307,8 @@ dizesiyle `PUT /api/custom-models/<id>`) ve web kontrol paneli aracılığıyla
307
307
ayarlayabilir veya düzenleyebilirsiniz. Yönlendirilen slug ayırıcısıyla
308
308
çakışacağı için `/` işareti reddedilir.
309
309
310
+
`GET /v1/catalog`, bir model listesini okumanın yönetici belirtecine mal olmaması için vardır. Rota salt okunurdur (`GET` ve `HEAD`), `x-opencodex-api-key`, bearer belirteci veya `x-api-key` kabul eder ve yönetim rotasıyla tamamen aynı baytları sunar. Yanıtlar güçlü bir `ETag` taşır — tam belge yerine `304` almak için `If-None-Match` ile geri gönderin — ve `Cache-Control: private, no-cache` içerir. Burada kabul edilen bir veri düzlemi anahtarı yönetim düzleminde **hiçbir şey** kazanmaz: `/api/catalog` ve tüm `/api/*` rotaları hâlâ yönetici belirteci veya pano oturumu gerektirir.
311
+
310
312
Görünen ad **yalnızca görüntüleme amaçlıdır ve yeniden oluşturma boyunca
311
313
kararlıdır**. Her `ocx sync` ve katalog yenilemesi yönlendirilen girdileri
312
314
`config.json`'dan (`customModels` dahil) yeniden türetir, böylece yapılandırılan
0 commit comments