Client Oluşturma

Korumalı bir endpoint'i çağırabilmek için bir API client'ına ihtiyacınız vardır. Client; izinlerinizin, grant türlerinizin, IP izin listenizin, hız sınırlarınızın, aylık kullanım kotanızın, kullanım sürenizin ve (isteğe bağlı) client sertifikanızın bağlandığı kimliktir.

Client'lar platform operatörü tarafından admin panelinden oluşturulur; client oluşturan bir partner endpoint'i yoktur. Bu sayfa size verilenleri ve çağrılarınızı etkileyen client ayarlarını açıklar.

Size verilen kimlik bilgileri

Öğe	Açıklama
client_id	UUID, örneğin c1a9beda-b14c-4eb5-b880-113023e6fc2d. Her token isteğinde gönderilir.
client_secret	Yüksek entropili gizli anahtar, her token isteğinde gönderilir. Parola gibi davranın ve bir secret manager'da saklayın.
Client sertifikası + özel anahtar	Yalnızca client sertifika gerektiriyorsa. Özel anahtar üretim anında bir kez gösterilir. Bkz. mTLS Client Sertifikaları.

Çağrılarınızı etkileyen client ayarları

Her korumalı çağrı, client'ınızı okuyan bir kontrol zincirinden geçer. Başarısız bir kontrol, herhangi bir iş mantığı çalışmadan reddedilir.

Grant türleri (grant_types)

Client'ın kullanabileceği OAuth grant'ları: client_credentials, password, refresh_token. Token endpoint'i client'ta tanımlı olmayan bir grant'ı reddeder. Bkz. Token Oluşturma.

Scope'lar (scopes)

client_credentials token'ının taşıdığı izinler. Her endpoint sayfası gerektirdiği izni listeler; bu izne sahip olmayan bir token gateway'de 403 ile reddedilir. password grant'ı ile alınan token'lar bunun yerine supervisor'ın rol izinlerini taşır.

Token ömrü (token_expiry)

client_credentials grant'ı ile verilen token'ların ömrü: enabled ve duration. enabled false ise token'lar süresizdir (expires_in: 0); refresh token'lar yine de 365 günle sınırlıdır. password grant'ı sabit ömürler kullanır (15 dakika / 30 gün).

Bir client'ın aynı anda tek bir geçerli access token'ı vardır: yeni bir token almak öncekini geçersiz kılar. Bkz. Token Oluşturma.

Kullanım süresi (expires_at)

Tanımlıysa, client bu zamandan sonra hiçbir grant ile token vermez (token endpoint'i 10004, client has expired kodunu döner).

IP izin listesi (allowed_ips)

Tekil IP'ler ve/veya CIDR blokları:

["203.0.113.42", "203.0.113.0/24", "2001:db8::/32"]

Boş liste kısıtlama olmadığı anlamına gelir. Boş olmayan bir listenin dışındaki bir adresten gelen çağrı 401 ile reddedilir. İzin listesi API çağrılarına uygulanır; token endpoint'i bunu kontrol etmez.

Hız sınırı (rate_limit)

Alan	Açıklama
requests_per_second	İlk kontrol edilir
requests_per_minute	İkinci kontrol edilir
requests_per_hour	Üçüncü kontrol edilir

0 değeri o pencereyi devre dışı bırakır. Bir pencere aşıldığında çağrı 429, kod 10011, bir Retry-After başlığı ve aşılan pencerenin başlıklarıyla reddedilir; örneğin X-Ratelimit-Limit-Second / X-Ratelimit-Remaining-Second (benzer şekilde -Minute, -Hour).

Aylık kullanım sınırı (monthly_limit)

İstek sayısıyla değil endpoint skorlarıyla ölçülen aylık kota. Bkz. Kullanım / Skor. Client'ın aylık sınırı varsa her yanıt X-Monthlylimit-Limit, X-Monthlylimit-Used ve X-Monthlylimit-Remaining başlıklarını taşır; kota dolduğunda çağrılar 429, kod 10012 ve Retry-After: 3600 ile reddedilir. 0 aylık sınır olmadığı (ve başlık dönmediği) anlamına gelir.

Client sertifikası (require_certificate)

true olduğunda token isteği dahil her çağrı, client'a verilen sertifikayı TLS el sıkışmasında sunmalıdır. Hatalar 401 döner. Bkz. mTLS Client Sertifikaları.

Aktiflik (is_active)

Operatör bir client'ı silmeden devre dışı bırakabilir. Aktif olmayan bir client token alamaz (kod 10002).

Operasyon kontrol listesi

• client_id, client_secret ve verildiyse sertifikanın özel anahtarını bir secret manager'da saklayın.
• Canlıya çıkmadan önce allowed_ips için çıkış IP / CIDR'larınızı operatöre iletin.
• Client'ın token'ını tek bir süreç yönetsin ya da her süreç için ayrı bir client kullanın: yeni bir token öncekini geçersiz kılar.
• X-Monthlylimit-Remaining değerini izleyin ve sıfıra ulaşmadan kota artışı isteyin.
• Sertifikanın ve client'ın expires_at değerinin bitişini takip edin ve operatörden zamanında yenilemesini isteyin.