> For the complete documentation index, see [llms.txt](https://docs.kangal.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kangal.dev/tr/admin-api/auth-pagination-errors.md). # Authentication, pagination ve hatalar ## Kullanıcı access token'ları `POST /auth/login` ile kullanıcı session'ı oluşturun: ```bash curl -fsS -X POST \ -H 'Content-Type: application/json' \ "$KANGAL_URL/auth/login" \ -d '{ "username": "admin@example.com", "password": "REDACTED", "tenant_id": "tenant-acme" }' | jq ``` Yanıt `access_token`, `token_type`, `expires_in` ve `refresh_token` içerir. İki token'ı da source control ve log dışında tutun. Kullanıcı access JWT'si mevcut audit-list route'u için zorunludur; standart Admin API dependency'leri tarafından da kabul edilir. ## Admin API token'ları Admin API token'ları machine credential'dır. Authentication yapılmış admin writer ile oluşturun: ```bash curl -fsS -X POST \ -H "Authorization: Bearer $ADMIN_ACCESS_TOKEN" \ -H 'Content-Type: application/json' \ "$KANGAL_URL/api/v1/admin/api-tokens" \ -d '{ "name": "production-readonly-exporter", "tenant_id": "tenant-acme", "scopes": ["admin:read"] }' | tee token-create.json | jq ``` Secret `kangaladm_` ile başlar ve plaintext yalnızca bu create response içinde döner. Kangal geri alınabilir plaintext yerine hash ve görünen prefix saklar. Token'ı hemen yetkili secret manager'a koyun ve response artifact'ini kaldırın. Desteklenen scope davranışı: | Scope | Etki | | ------------------ | ----------------------------------------- | | `admin:read` | GET, HEAD ve OPTIONS Admin API çağrıları. | | `admin:write` | Write çağrıları ve read çağrıları. | | `admin:*` veya `*` | Tüm Admin API method scope'ları. | Varsayılan scope read'dir. Read-only token salt okunur admin rolü, writer token admin rolü olarak temsil edilir. Revoke edilmiş veya süresi dolmuş token authentication'ı geçemez. Normal admin kendi yetkisi içinde tenant-scoped credential oluşturabilir. Global super-admin credential yalnızca super admin tarafından oluşturulabilir. Workload, tenant ve ortam başına ayrı token kullanın; expiry belirleyin, rotate edin ve workload kaldırıldığında revoke edin. ## Method-aware rol kontrolleri Standart admin dependency kullanan route'larda: | HTTP method'ları | Kabul edilen roller | | -------------------------------- | ----------------------------------------------------------- | | `GET`, `HEAD`, `OPTIONS` | `admin`, `super_admin`, `admin_readonly`, `read_only_admin` | | `POST`, `PUT`, `PATCH`, `DELETE` | `admin`, `super_admin` | Token scope ve rol, method'a birlikte izin vermelidir. Route'a özel RBAC ek şart getirebilir; observability tenant izin matrisinden `observability:read` veya `observability:write` ister. İşlemin anlamsal niyeti HTTP iznini değiştirmez. Configuration validate, diff, dry-run, snapshot create ve rollback preview işlemleri `POST` olduğu için write erişimi ister. ## Bearer kullanımı ```http Authorization: Bearer kangaladm_... ``` Credential'ı query parametresinde göndermeyin. TLS kullanın, proxy'lerde authorization header'ını redakte edin ve token içeren komutlar sırasında shell tracing (`set -x`) kullanmayın. ## Ortak liste pagination'ı Birçok kaynak listesinde: | Parametre | Davranış | | --------------- | -------------------------------------------------------- | | `limit` | Sayfa boyutu; shared helper'da normalde en fazla 1.000. | | `offset` | Sıfır tabanlı offset; negatif olamaz. | | `sort` | Endpoint'e özel allow-list içindeki alan. | | `order` | `asc` veya `desc`. | | `labelSelector` | Destekleyen route'larda opsiyonel kaynak label filtresi. | Shared helper yanıtları şu header'ları içerir: ```http X-Total-Count: 248 X-Limit: 100 X-Offset: 0 ``` ```bash curl -fsS -G \ -D /tmp/kangal-headers.txt \ -H "Authorization: Bearer $KANGAL_TOKEN" \ --data-urlencode 'tenant_id=tenant-acme' \ --data-urlencode 'limit=100' \ --data-urlencode 'offset=0' \ --data-urlencode 'sort=name' \ --data-urlencode 'order=asc' \ --data-urlencode 'labelSelector=environment=production' \ "$KANGAL_URL/api/v1/admin/gateways/gw-production/services" | jq grep -Ei '^x-(total-count|limit|offset):' /tmp/kangal-headers.txt ``` Pagination her endpoint'te aynı değildir. Endpoint şemasını kontrol edin: * Gateway listeleri shared pagination helper kullanmaz. * Route listesi shared pagination kullanır fakat `labelSelector` sunmaz. * Audit; `skip` (varsayılan 0), `limit` (varsayılan 50, en fazla 200) ve `sort_direction` kullanır, `X-Total-Count` döndürür. * Snapshot listesi `limit` (varsayılan 20, en fazla 100) kullanır ve düz dizi döndürür. * Observability request/anomaly aramasında `limit` en fazla 500; live polling'de en fazla 200'dür ve imzalı cursor kullanılır. * SLO timeline `limit` üst sınırı 500'dür. Endpoint metadata'sı olmadan tek bir generic paginator üretmeyin. Değişen veri kümelerinde offset pagination aynı öğeyi tekrarlayabilir veya atlayabilir; desteklenen sabit bir sort kullanın ve gerektiğinde resource ID ile tekilleştirin. ## Label selector ve sıralama `labelSelector` değerini yalnızca desteklenen endpoint'in tarif ettiği biçimde gönderin. Bozuk selector client error döndürür. Sort alanları kaynak bazında allow-list'tedir; service için kabul edilen alan target veya certificate için geçerli olmayabilir. Query parametrelerini OpenAPI'den bulun: ```bash curl -fsS "$KANGAL_URL/openapi.json" \ | jq '.paths["/api/v1/admin/gateways/{gateway_id}/services"].get.parameters' ``` ## Hata biçimi FastAPI hataları çoğunlukla `detail` alanını kullanır: ```json { "detail": "Missing authorization token" } ``` Request-model validation (`422`) alan hatalarını liste olarak döndürür: ```json { "detail": [ { "type": "missing", "loc": ["body", "name"], "msg": "Field required", "input": {} } ] } ``` Configuration parse ve domain-validation yanıtları kendi yapılandırılmış validation, diff, count veya error verilerini ekleyebilir. Token ve hassas yapılandırmayı redakte ederek tam response body'yi erişim kontrollü loglayın. ## Durum kodları | Kod | Anlam ve ilk kontrol | | ----- | --------------------------------------------------------------------------------------------------------------- | | `200` | Başarılı read/update veya operasyon sonucu. | | `201` | Kaynak/olay oluşturuldu. | | `204` | Response body olmadan başarılı işlem. | | `400` | Bozuk query/body, geçersiz cursor, parse hatası, tenant mismatch veya domain önkoşulu. `detail` alanını okuyun. | | `401` | Bearer token eksik, bozuk, geçersiz, süresi dolmuş veya revoke edilmiş. | | `403` | Authentication başarılı, ancak rol, scope, izin veya tenant erişimi yetersiz. | | `404` | İlgili tenant kapsamında kaynak görünmüyor/bulunamadı. | | `409` | Endpoint'in sunduğu durumda kaynak veya state çakışması. | | `422` | Request schema/alan validation başarısız. | | `429` | Rate limit aşıldı. Varsa retry yönlendirmesine uyun. | | `500` | İşlenmemiş server hatası. Request ID'yi alın ve API loglarını inceleyin. | | `503` | Service/readiness veya dependency erişilemiyor. `/ready` ve dependency'leri kontrol edin. | Güvenlik nedeniyle `404`, cross-tenant kaynağın varlığını gizlemek için de kullanılabilir. Yalnızca bunu 404 yokluktan ayırmak için tenant değiştirmeyin veya credential yetkisini genişletmeyin. ## Sağlam hata yönetimi ```bash response=$(mktemp) headers=$(mktemp) code=$(curl -sS \ -D "$headers" \ -o "$response" \ -w '%{http_code}' \ -H "Authorization: Bearer $KANGAL_TOKEN" \ -H 'X-Request-ID: destek-kaydi-8472' \ "$KANGAL_URL/api/v1/admin/gateways/gw-production/services?tenant_id=tenant-acme") || { echo 'Ağ veya TLS hatası' >&2 exit 1 } case "$code" in 2??) test -s "$response" && jq . "$response" ;; 401) echo 'Login/token yenileme yapın; aynı credential ile tekrar denemeyin.' >&2 jq . "$response" >&2 exit 1 ;; 403) echo 'Method rolünü, token scope, tenant ve route iznini kontrol edin.' >&2 jq . "$response" >&2 exit 1 ;; 429|503) echo "Geçici yanıt HTTP $code; güvenli işlemde sınırlı backoff uygulayın." >&2 jq . "$response" >&2 exit 1 ;; *) echo "Kangal API HTTP $code ile başarısız" >&2 jq . "$response" 2>/dev/null || cat "$response" >&2 exit 1 ;; esac ``` ## Retry kuralları * GET isteklerini connection hatası, `429` veya `503` durumunda sınırlı exponential backoff ve jitter ile tekrar deneyin. * Varsa `Retry-After` değerine uyun. * Timeout sonrası create/import/sync/rollback işlemini otomatik tekrarlamayın. Önce live state'i read/export ederek uygulanıp uygulanmadığını bulun. * Aynı `X-Request-ID` değerini yeniden kullanmak incelemeyi kolaylaştırır, write işlemini idempotent yapmaz. * Cursor polling'de generic retry loop yerine endpoint'in `poll_after_ms`, `has_more`, `gap_detected`, `cursor_expired` ve `next_cursor` alanlarını izleyin. ## Authorization sorunlarını giderme 1. Header'ın bulunduğunu ve `Bearer` şemasını kullandığını doğrulayın. 2. Token'ın mevcut API ortamına ait, geçerli ve revoke edilmemiş olduğunu kontrol edin. 3. HTTP method'unu rol tablosuyla karşılaştırın. 4. Admin API token'ında scope'un `admin:read`, `admin:write` veya wildcard olduğunu inceleyin. 5. Tenant atamasını ve açık `tenant_id` değerini kontrol edin. 6. `observability:read` gibi route'a özel izni doğrulayın. 7. `/admin/audits/` için `/auth/login` üzerinden kullanıcı access JWT'si kullanın. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.kangal.dev/tr/admin-api/auth-pagination-errors.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.