Bir ağ geçidi API anahtarı oluşturun veya bir kullanıcı JWT'si alın ve hangi CID222 yüzeyinin bu ikisinden hangisini kabul ettiğini öğrenin.

CID222, Authorization başlığında iki kimlik bilgisi kabul eder ve bunlar birbirinin yerine geçmez. Ağ geçidi API anahtarı, sunucudan sunucuya trafik için bir kiracıyı tanımlar. Kullanıcı JWT'si, oturum açmış bir kişiyi tanımlar ve oturumlara, görüntü analizine ve belge analizine erişebilen tek kimlik bilgisidir.

Neye ihtiyacım var?

Lisans: Any
Rol: admin_usernormal_user

Ön koşullar

Cihaz ilk açılış kurulum sihirbazını tamamlamıştır.
Ağ geçidi API anahtarı oluşturmak veya iptal etmek admin_user rolünü gerektirir; JWT almak yalnızca bir kiracı hesabı gerektirir.
İstemciniz ağ geçidine TCP 443 üzerinden, konteynere doğrudan çağrı yapıyorsanız TCP 3000 üzerinden erişebilir.

Hangi kimlik bilgisi hangi yüzeye erişir

Her iki kimlik bilgisi de aynı biçimde, Authorization: Bearer <credential> olarak gönderilir. CID222 bunları cid_key_ önekinden ayırt eder. Farklı olan, her birinin nerede kabul edildiğidir.

Yüzey	Ağ geçidi API anahtarı	Kullanıcı JWT'si
`POST /chat/completions`	Evet	Evet
`POST /chat/harden-prompt`	Evet	Evet
`GET /chat/providers`	Evet	Evet
`GET /models`	Evet	Evet
`POST /api/v1/guardrails/detect`	Evet	Evet
`/sessions` ve `/sessions/:id/…`	Hayır	Evet
`/image-analysis/…`	Hayır	Evet
`/document-analysis/…`	Hayır	Evet
`/admin/…`, `/admin/api-keys` dahil	Hayır	Evet, `admin_user` ile

Warning

/sessions, /image-analysis veya /document-analysis üzerinde bir ağ geçidi API anahtarı 401 döndürür. Bu denetleyiciler yalnızca JWT doğrulamasıyla korunur; anahtar hiç incelenmez. Aksini söyleyen belgeler kodu değil, bir niyeti anlatmaktadır.

Ağ geçidi API anahtarı oluşturun ve kullanın

API anahtarı listesini açın

Yönetim → API Anahtarları yolunu seçin.

Sayfa, kiracının mevcut anahtarlarını adları, kapsamları ve son kullanma tarihleriyle listeler. Gizli değerin kendisi listelenmez — CID222 yalnızca SHA-256 özetini saklar.

Anahtarı oluşturun

API Anahtarı Oluştur düğmesini seçin, anahtarı kullanacak çağırana göre adlandırın ve anahtarın kendiliğinden çalışmayı bırakmasını istiyorsanız bir son kullanma tarihi belirleyin. Son kullanma alanını boş bırakmak, anahtarın hiç sona ermeyeceği anlamına gelir.

Yeni anahtar bir kez gösterilir: cid_key_ ve ardından 64 onaltılık karakter — onaltılık olarak yazılmış 32 rastgele bayt.

İletişim kutusunu kapatmadan anahtarı kopyalayın

API Anahtarını Kopyala düğmesini seçin ve değeri gizli anahtar yöneticinize veya bir ortam değişkenine kaydedin.

İletişim kutusunu kapatmak açık metni atar. Değeri kaybederseniz anahtarın satırında API Anahtarını Yenile düğmesini seçin; bu, yeni bir gizli değer üretir ve eskisini anında geçersiz kılar.

Ağ geçidini anahtarla çağırın

Anahtarı bir bearer token olarak gönderin.

curl -N -sS -X POST "https://<appliance-fqdn>/chat/completions" \
  -H "Authorization: Bearer cid_key_0123456789abcdef…" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o","provider":"openai","messages":[{"role":"user","content":"Hello"}]}'

Yanıt bir SSE akışıdır. Reddedilen bir anahtar, Invalid API key mesajıyla 401 döndürür.

Danger

Bir kiracı grubuna atanmış anahtar, gruba en önce eklenen üyeye atfedilir. O kullanıcıyı kaldırmak anahtarı iptal etmez; anahtarın kimliğini başka bir üyeye devreder. Anahtarın sahibi olan kişi ayrıldığında anahtarın kendisini iptal edin.

Kullanıcı JWT'si alın ve kullanın

Kimlik bilgilerini token ile değiştirin

Kullanıcı adını ve parolayı POST /auth/login adresine gönderin.

curl -sS -X POST "https://<appliance-fqdn>/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"username":"jdoe","password":"<password>"}'

Uç nokta, token'ı ve çağıranın kimliğini 200 ile döndürür.

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…",
  "tenant_id": "b2c3d4e5-6f70-4a81-9b2c-3d4e5f607182",
  "username": "jdoe",
  "contact_email": "jdoe@example.corp",
  "role": "normal_user"
}

Token'ı sonraki her istekte gönderin

access_token değerini Authorization başlığına koyun.

curl -sS "https://<appliance-fqdn>/sessions" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…"

İstek, token'da kodlanmış kiracı için başarılı olur. Silinmiş veya devre dışı bırakılmış bir kiracıya ait token, süresi dolmadan önce bile 401 döndürür.

Token süresi dolduğunda yeniden kimlik doğrulayın

Token'lar HS256'dır ve varsayılanı 24 saat olan JWT_EXPIRES_IN değeri kadar yaşar. Her token sunucu tarafında tutulan bir oturuma bağlıdır, dolayısıyla erken de sona erebilir: kullanıcı çıkış yapar, parolasını değiştirir, bir yönetici Her yerden çıkış yap komutunu kullanır veya hesap devre dışı bırakılır. API çağrıcılarına yenileme token'ı verilmez; süresi dolmuş ya da iptal edilmiş bir token, POST /auth/login yeniden çağrılarak değiştirilir. (Panel farklıdır: X-CID-Session: cookie ile giriş yapar, oturumu httpOnly çerezlerde tutar ve POST /auth/sessions/refresh ile yeniler. Entegrasyonlar bu modu kullanmamalıdır.)

Süresi dolmuş veya iptal edilmiş token, code değeri SESSION_EXPIRED olan 401 döndürür. Kimlik doğrulamalı herhangi bir çağrıda alınan 401'i, yeniden giriş yapıp isteği bir kez yineleme işareti olarak değerlendirin.

Token neyi taşır

{
  "sub": "b2c3d4e5-6f70-4a81-9b2c-3d4e5f607182",
  "username": "jdoe",
  "role": "normal_user",
  "iat": 1789200000,
  "exp": 1789286400
}

Talep	Anlamı
`sub`	Token'ın doğruladığı kiracı kimliği
`username`	Hesap adı
`role`	Token üretildiği andaki rol
`iat`	Üretim zamanı, Unix döneminden bu yana saniye
`exp`	Sona erme zamanı, Unix döneminden bu yana saniye

role talebi bilgilendirme amaçlıdır. CID222 rolü her istekte veritabanından yeniden okur; bu nedenle bir yetki düşürmesinden önce üretilmiş token eski rolü korumaz.

Roller

Rol	Neler yapabilir
`superadmin`	Tüm kiracılar genelinde her şey
`admin_user`	Kiracı, kimlik bilgisi, filtre ve anahtar yönetimi, ayrıca sohbet ve oturumlar
`normal_user`	Kendi kiracısı için sohbet, oturumlar ve analiz uç noktaları
`viewer`	Salt okunur. Değişiklik yapan her istek `READ_ONLY_ROLE` ile reddedilir
`auditor`	Estateyi inceler. Sohbet ve oturum yazmaları `ROLE_NOT_FOR_CHAT` ile reddedilir

Ağ geçidi API anahtarıyla doğrulanmış bir isteğe sentetik api_key rolü verilir. Bu, bir kiracıya atayabileceğiniz bir rol değildir.

Oturum açmada hız sınırlama

POST /auth/login, istemci IP adresi başına dakikada 10 istek kabul eder. POST /auth/forgot-password ve POST /auth/reset-password dakikada 5 istek kabul eder. Sınırın aşılması 429 döndürür.

Başka hiçbir uç nokta hız sınırlı değildir ve CID222 hiçbir yanıtta X-RateLimit-* başlığı göndermez.

Hata biçimleri

Hata gövdesi tekbiçimli değildir; bu nedenle önce HTTP durum koduna, yalnızca mevcut olduğunda da code alanına bakın.

Hatalı parola veya eksik bearer token gibi çerçeve düzeyindeki bir reddetme code taşımaz:

{
  "statusCode": 401,
  "message": "Invalid credentials",
  "error": "Unauthorized"
}

CID222 politika reddi, makine tarafından okunabilir bir code ve bazen ek alanlar taşır:

{
  "statusCode": 403,
  "code": "ROLE_NOT_FOR_CHAT",
  "message": "This role does not use the chat: an auditor reviews the estate rather than adding traffic to it. Use the dashboard instead."
}

Doğrulama

Ağ geçidi API anahtarıyla GET /models çağırın. 200 ve bir JSON dizisi döndürür.
Aynı ağ geçidi API anahtarıyla GET /sessions çağırın. 401 döndürür — bu beklenen reddetmedir ve anahtarın belgelendiği gibi kapsamlandığını doğrular.
POST /auth/login ile alınmış bir JWT ile GET /sessions çağırın. 200 ve kiracının oturumlarından oluşan bir dizi döndürür.
Yönetim → API Anahtarları yolunu seçin. Anahtarın satırı, test çağrınızı yansıtan bir son kullanım zaman damgası gösterir.

Sonraki adımlar

API genel bakış — her uç nokta, temel yolu ve koruyucusu.
Sohbet API'si — /chat/completions üzerindeki istek gövdesi ve SSE sözleşmesi.
Oturumlar API'si — konuşma durumunu tutan, yalnızca JWT kabul eden yüzey.

Kimlik doğrulama