> 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/developer-portal/credentials-sdks-domains.md). # Credential, SDK ve domain Geliştirici Portalı birbirinden ayrı üç yaşam döngüsünü bir araya getirir: 1. Uygulama, consumer kimlik bilgisi oluşturur. 2. API sürümü, SDK dışa aktarımında kullanılan değiştirilemez sözleşmeyi sağlar. 3. Özel alan adı kaynağı, DNS sahipliğini doğrular ve portal edge binding'ini etkinleştirir. Bu kaynakları ayrı yönetin. Tema alanındaki `custom_domain` portal metadata'sını, özel alan adı kaynağı ise DNS ve sertifika yaşam döngüsünü yönetir. SDK dışa aktarımı kimlik bilgisi üretmez veya pakete kimlik bilgisi eklemez. ## Portal API anahtarları Otomatik onaylanan bir kayıt veya başarılı manuel onay, rastgele `mgk_...` değerine sahip bir `api_key` oluşturur. Anahtar depolamada şifrelenir ve blind index üzerinden aranır. Çalışma zamanı araması; süresi dolmuş, iptal edilmiş, devre dışı, etkin olmayan, askıya alınmış veya silinmiş kimlik bilgilerini reddeder. Kimlik bilgisini oluşturan otomatik kayıt veya başarılı onay yanıtındaki `credential.key` değerini alın ve doğrudan onaylı bir secret store'a aktarın. ```json { "status": "active", "consumer": { "id": "consumer-id", "username": "portal-dev-mobile-checkout", "tenant_id": "acme" }, "credential": { "id": "credential-id", "type": "api_key", "key": "mgk_...", "expires_at": "2026-07-18T12:00:00Z" } } ``` Anahtarı yaşam döngüsü boyunca production secret olarak yönetin. Admin API ve audit log erişimini yalnızca yetkili operatörlerle sınırlandırın, destek materyallerindeki kimlik bilgisi değerlerini maskeleyin ve oluşturma yanıtını consumer workload'a kontrollü aktarım için kullanın. ### Geçerlilik süresi ve API sürümleri * `ttl_seconds` pozitif olmalıdır; şema düzeyinde üst sınırı yoktur. * Sürümde `sunset_at` varsa istenen TTL ile `sunset_at` değerlerinden erken olanı kullanılır. * TTL ve `sunset_at` yoksa üretilen API anahtarına otomatik sona erme zamanı atanmaz. * Kullanım dışı bir sürüm emekliye ayrılana kadar listelenir. `sunset_at` zamanında bu sürüm için yeni abonelikler ve kimlik bilgisi üretimi engellenir. * Bağlı API sürümü emekliye ayrıldığında kimlik bilgilerinin süresi hemen sona erer ve uygulama `suspended_api_version` durumuna geçer. {% hint style="warning" %} Kullanım dışı bir sürümde `sunset_at` ayarlamak, bağlı kimlik bilgilerinin sona erme zamanını bu değere taşır. Daha ileri bir `sunset_at` seçmeden önce kısa ömürlü kimlik bilgilerini inceleyin; geçerlilik süreleri yeni tarihe uzayabilir. {% endhint %} ### Yetkilendirme gereksinimleri `requested_scopes`, uygulamada saklanan erişim talebi metadata'sıdır. Anahtarın gerçek erişimi, ilgili consumer için gateway route ve kimlik doğrulama yapılandırması tarafından belirlenir. Route düzeyindeki yetkilendirme policy'lerini yapılandırıp test edin; görüntülenen scope adlarını uygulanmış iznin doğrulaması olarak kullanmayın. ### Anahtarı iptal etme veya değiştirme Açığa çıkan portal API anahtarını silin: ```bash curl -sS -X DELETE \ "$KANGAL_ADMIN_URL/admin/consumer-credentials/$CREDENTIAL_ID" \ -H "Authorization: Bearer $ADMIN_TOKEN" ``` Ardından yeni bir uygulama kaydıyla veya tenant kapsamındaki Admin Credential API ile yeni anahtar oluşturun. Bekleyen bir uygulamanın reddedilmesi kimlik bilgisi üretimini engeller. Uygulama durumu ve kimlik bilgisi iptali ayrı işlemlerdir; etkin uygulamanın kimlik bilgisini açıkça silin. Üretilmiş istemciler, API anahtarıyla korunan gateway route'unu çağırırken şu header'ları gönderebilir: ``` X-Tenant-ID: X-Gateway-ID: X-API-Key: ``` Kullanılacak kesin header'lar route üzerinde kurulu kimlik doğrulama plugin'lerine göre belirlenir. ## Üretilmiş SDK'lar SDK dışa aktarımı; yayıncı tenant'ta okuma yetkili bir yönetici, `developer_portal.manage` yetkisi, herkese açık bir servis ve saklanmış OpenAPI snapshot'ı bulunan yayımlanmış veya `sunset_at` zamanı gelmemiş kullanım dışı bir API sürümü gerektirir. Desteklenen hedefler: | `target` | Minimum çalışma zamanı | Taşıma | | ------------------ | ---------------------- | --------------- | | `typescript-fetch` | ES2022 | Fetch | | `python` | Python 3.9 | `urllib` | | `go` | Go 1.21 | `net/http` | | `java` | Java 11 | `java.net.http` | | `csharp` | .NET 8 | `HttpClient` | | `php` | PHP 8.1 ve ext-curl | cURL | API üzerinden dışa aktarın: ```bash curl -sS \ "$KANGAL_ADMIN_URL/portal/services/$SERVICE_ID/versions/$VERSION_ID/sdk?tenant_id=$TENANT_ID&gateway_id=$GATEWAY_ID&target=python" \ -H "Authorization: Bearer $ADMIN_TOKEN" ``` Veya repository CLI'ını kullanın: ```bash python scripts/kangalctl.py sdk export \ --service-id "$SERVICE_ID" \ --version-id "$VERSION_ID" \ --gateway-id "$GATEWAY_ID" \ --target python \ --output orders-sdk.zip ``` API, ZIP byte'ları yerine şu alanları içeren JSON yanıtı döndürür: | Alan | Anlamı | | ----------------------- | -------------------------------------- | | `schema_version` | Artifact sözleşmesi; güncel değer `2` | | `filename` | Güvenli hale getirilmiş `.zip` adı | | `media_type` | `application/zip` | | `encoding` | `base64` | | `sha256` / `size_bytes` | Arşivin tamamı için bütünlük değerleri | | `contract_sha256` | Canonical saklanmış OpenAPI checksum'ı | | `generator` | Ad, `2.1.0` sürümü ve hedef | | `files` | Arşiv dosya envanteri | | `content` | Base64 arşiv byte'ları | ZIP; üretilmiş istemci kaynaklarını, paket metadata'sını, eksiksiz `REFERENCE.md` metot indeksini, `openapi.json`, `checksums.sha256` ve `sdk-manifest.json` dosyalarını içerir. Üretim; canonical JSON, sıralı dosyalar, sabit ZIP zaman damgaları ve dosya modlarıyla deterministiktir. Üretilmiş istemciler; her OpenAPI operation için public bir SDK metodu ve route'lardan türetilen genel istek fallback'i, çalışma zamanında `baseUrl`, API anahtarı ve Bearer token seçenekleri, yayımlanmış tenant/gateway header varsayılanları, istek bazında override ve dile uygun API hataları sunar. Kimlik bilgileri pakete gömülmez. Retry durumları hedefe göre değişir; ayrıntılar için [Authentication, retry ve hatalar](/tr/sdklar/security-and-errors.md) bölümüne bakın. {% hint style="warning" %} SDK, API sürümüyle saklanan route tabanlı OpenAPI snapshot'ını kullanır. Sürüm oluşturulduktan sonra yapılan route değişiklikleri mevcut artifact'i değiştirmez; `specification_url` ayrı bir dokümantasyon bağlantısı olarak kalır. Üretilen paketi yayımlamadan önce snapshot'ın amaçlanan route, metot, path ve müşteriye yönelik açıklamaları içerdiğini doğrulayın. {% endhint %} Consumer'lar SDK dışa aktarma endpoint'ini çağırmamalı veya Admin API token'ı bulundurmamalıdır. Platform ekipleri arşivi doğrulayıp onaylı bir registry ya da dağıtım kanalı üzerinden yayımlamalıdır. Ayrıntılar için [SDK'lara genel bakış](/tr/sdklar/sdks.md), [üretilmiş istemci iş akışı](/tr/sdklar/api-client.md) ve [dil hızlı başlangıçları](/tr/sdklar/language-quickstarts.md) bölümlerine bakın. Resmi control plane istemci yüzeyi [Admin API SDK method referansında](/tr/sdklar/admin-api-methods.md) listelenir. ## Portal özel alan adları Portal alan adları iki ayrı kaynakta yönetilir: * `PUT /portal/theme`, görüntüleme amaçlı `custom_domain` metadata'sını saklar. * `target: "portal"` ile `POST /admin/gateways/{gateway_id}/custom-domains`, DNS sahipliği, sertifika, SNI ve binding yaşam döngüsünü oluşturur. Hostname'i etkinleştirmek için özel alan adı kaynak iş akışını kullanın. ### Portal alan adı oluşturma Yönetici özel alan adı endpoint'lerinin `/api/v1/admin/...` alias'ları da vardır. ```bash curl -sS -X POST \ "$KANGAL_ADMIN_URL/admin/gateways/$GATEWAY_ID/custom-domains" \ -H "Authorization: Bearer $ADMIN_TOKEN" \ -H 'Content-Type: application/json' \ -d "{ \"tenant_id\": \"$TENANT_ID\", \"hostname\": \"developers.example.com\", \"target\": \"portal\", \"dns_provider\": \"manual\", \"dns_provider_config\": {}, \"dns_credentials\": {}, \"acme_provider\": \"test-ca\", \"acme_config\": {}, \"dry_run\": true }" ``` Hostname'ler IDNA ile normalize edilir, somut ve tam nitelikli alan adı olmalı ve tenant'lar arasında global olarak benzersiz olmalıdır. Wildcard, IP adresi, localhost, geçersiz etiket veya mevcut SNI ile çakışan değerler reddedilir. Oluşturma yanıtı şu bilgileri içerir: ``` challenge_record_name: _kangal-verification.developers.example.com challenge_value: kangal-domain-verification= challenge_expires_at: <24 hours after creation> status: pending_dns ``` Tam TXT değerini DNS sağlayıcınızda yayımlayın ve ardından doğrulayın: ```bash curl -sS -X POST \ "$KANGAL_ADMIN_URL/admin/gateways/$GATEWAY_ID/custom-domains/$DOMAIN_ID/verify?tenant_id=$TENANT_ID" \ -H "Authorization: Bearer $ADMIN_TOKEN" ``` Başarılı doğrulama challenge sürümünü tüketir ve tek bir idempotent sertifika işi kuyruğa alır. Doğrulamadan önce süresi dolan veya açığa çıkan challenge'ı `POST .../challenge` ile yenileyin. Etkinleştirmeden sonra `POST .../renew` sertifika yenilemeyi kuyruğa alır. `issuance_failed` durumunda `POST .../retry` ile yeniden deneyebilirsiniz; deployment güvenlik ayarları izin veriyorsa `dry_run` değeri override edilebilir. Gateway arayüzünde manuel DNS veya Cloudflare doğrulaması seçilebilir. Cloudflare doğrulaması için `zone_id` ve API token gerekir; TXT kaydını DNS yönetim arayüzünüzde yayımlayın. Sertifika sağlayıcısı olarak yerleşik test CA veya cert-manager seçilebilir. `dry_run` varsayılan olarak `true` değerindedir. Production cert-manager sertifikası için deployment'ta herkese açık ACME güvenlik ayarını etkinleştirin. Yaygın durumlar `pending_dns`, `verification_failed`, `issuance_pending`, `issuing`, `issuance_failed`, `active`, `renewal_due`, `renewing` ve `renewal_failed` değerleridir. Yenileme başarısız olduğunda önceki etkin sertifika ve SNI korunur; `last_error` ile sona erme uyarısı durumu görüntülenir. ### Edge binding gereksinimleri Başarılı sertifika üretimi, `portal` hedefi ve `/portal/{tenant_id}` portal path'i ile bir `custom_domain_bindings` kaydı oluşturur. Bu kaydı release sırasında Helm binding'iyle veya incelenmiş bir edge controller ile Ingress, Gateway API, DNS ya da harici load balancer'a uygulayın. Herkese açık trafiği yönlendirmeden önce edge route ve TLS path'ini uçtan uca doğrulayın. Alan adı silindiğinde bekleyen işler iptal edilir ve yönetilen sertifika/SNI durumu kapatılır. Harici DNS ve edge kaynaklarını da ilgili sağlayıcılardan kaldırın. ## Sorun giderme | Belirti | Kontrol | | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | Yeni uygulama kimlik doğrulayamıyor | Oluşturma veya onay akışında üretilen anahtarın workload secret store'una aktarıldığını doğrulayın; açığa çıkma şüphesinde anahtarı değiştirin | | İstenen scope beklenen erişimi sağlamıyor | Consumer'ın route ve kimlik doğrulama policy'lerini kontrol edip yetkilendirmeyi test edin | | SDK dışa aktarımında `409` | Sürümün yayımlandığını, sunset zamanının gelmediğini ve saklanmış sözleşmesinin bulunduğunu doğrulayın | | SDK hedefinde `422` | Belgelenen altı hedef kimliğinden birini kullanın | | Alan adı doğrulaması başarısız | TXT kayıt adı/değeri, 24 saatlik challenge süresi, DNS yayılımı ve seçilen resolver/provider ayarını kontrol edin | | Alan adı `active` ancak erişilemiyor | Edge binding, frontend route, TLS secret, DNS A/AAAA/CNAME ve load balancer yapılandırmasını doğrulayın | | `dry_run` ile portal production trafiği almıyor | Production sertifikası için `dry_run=false` ve gerekli herkese açık ACME güvenlik ayarını 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/developer-portal/credentials-sdks-domains.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.