Unauthorized (Yetkisiz) API Erişim Hatası: Sebepleri ve Çözüm Rehberi

Kısa Cevap — Domain Name API REST API'sini kullanırken 401 Unauthorized, Authentication Failed, Access Denied veya Unauthorized API Access hatası alıyorsanız, bu hata çoğu durumda Reseller ID, API Key veya IP Whitelist yapılandırmanızdan kaynaklanır. Sisteme gönderdiğiniz kimlik bilgilerinin reddedildiğini gösterir; sunucu veya domain ile ilgili bir arıza değildir. Reseller ID ve API Key'inizi Entegrasyon Bilgileri sayfasından doğrulamak, çoğu vakada sorunu birkaç dakika içinde çözer.

Hızlı Tanım — 401 Unauthorized = “kimsin, bunu bilemiyorum.” Sunucu isteği işlemeden, kimlik doğrulama adımında durdu. Çözüm her zaman kimlik bilgileriniz (Reseller ID, API Key, IP Whitelist) etrafında aranır; domain verisiyle veya seçtiğiniz uzantıyla ilgisi yoktur.

Not — Not: yukarıdaki tablonun “Anlamı” ve “Tipik sebep” satırları genel HTTP standardını anlatır (RFC 7235). Domain Name API'nin kimlik doğrulama hataları için döndürdüğü mesajlar (Unauthorized, Authentication Failed, Access Denied gibi) pratikte hep aynı kök nedene — kimlik bilgisi sorununa — işaret eder; bu rehberin geri kalanı da o kök nedene odaklanır.

Reseller ID ve API Key

Reseller ID: Hangi bayi hesabı adına işlem yapıldığını tanımlayan benzersiz değer. API Key: Bu hesaba erişim için kullanılan kimlik doğrulama anahtarı. Her ikisini de panelinizde Hesabım > Bayi Ayarları > Entegrasyon Bilgileri sayfasından görebilir, gerekirse “Bilgileri E-posta Gönder” butonuyla kayıtlı e-posta adresinize yeniden gönderebilirsiniz.

Live ve Test Ortamı: İki Farklı API Key

Entegrasyon Bilgileri sayfasında iki ayrı API Key görürsünüz: Live Environment API Key ve Test Environment API Key. Live anahtar gerçek domain işlemleri için kullanılır ve bayi hesabınıza fatura edilir; Test anahtarı ise geliştirme ve entegrasyon testleri için kullanılır, ücretlendirilmez ve gerçek kayıt oluşturmaz.

Sık Görülen Karışıklık — Test ortamı için aldığınız API Key'i Live ortam endpoint'ine (veya tersini) göndermek, kimlik bilgileri “görünüşte doğru” olsa bile Unauthorized hatasına yol açabilir. Yeni bir entegrasyona her zaman Test ortamıyla başlayıp, testler başarılı olduktan sonra Live ortama geçmeniz önerilir.

IP Whitelist: Ek Bir Güvenlik Katmanı

Reseller ID ve API Key doğru olsa bile, isteğin geldiği sunucu IP adresi panelinizde tanımlı IP Whitelist listesinde değilse istek reddedilebilir. Bu konuyu, gerçek panel ekran görüntüleriyle birlikte bu rehberin 2. bölümünde detaylı olarak ele alacağız.

1) Yanlış veya Eksik API Key

Belirti: Her istekte, domain veya işlem türünden bağımsız olarak sürekli Unauthorized hatası alırsınız.

Sebep: Modülünüze veya kodunuza girilen API Key, panelinizdeki güncel değerle eşleşmiyor. Bu genellikle anahtarın eksik kopyalanması, eski bir anahtarın hâlâ kullanılıyor olması veya anahtar yenilendiğinde uygulamanın güncellenmemesinden kaynaklanır.

Çözüm: Entegrasyon Bilgileri sayfasından güncel API Key'i kopyalayın ve kullandığınız ortama (Live/Test) uygun olanı girdiğinizden emin olun.

2) Yanlış Reseller ID

Belirti: API Key doğru olduğu halde hata devam eder.

Sebep: Reseller ID, API Key kadar kritik bir bileşendir; sistem önce hangi hesaba ait olduğunuzu anlamaya çalışır. Yanlış veya eski bir Reseller ID girilmesi, doğru API Key ile birlikte gönderilse bile isteği geçersiz kılar. 

Çözüm: Reseller ID'nizi Entegrasyon Bilgileri sayfasından doğrulayın; özellikle hesap taşıma (migration) sonrası bu değerin değişmiş olabileceğini unutmayın.

3) Reseller ID Alanına E-posta Adresinin Yazılması

Belirti: Modül veya kod, kullanıcı adı alanına panel giriş e-postanızı içeriyor.

Sebep: Bu, kimlik doğrulama hatalarının en sık görülen tek nedenidir. Bazı kullanıcılar “Kullanıcı Adı” alanını panele giriş yaptıkları e-posta adresiyle dolduruyor; ancak Domain Name API bu alanda e-posta değil, Reseller ID bekler. Bu konuyu, ilişkili “Reseller Not Found” hatasını ele alan ayrı rehberimizde de detaylı olarak işliyoruz.

Çözüm: İlgili alana e-posta adresinizi değil, Entegrasyon Bilgileri sayfasındaki gerçek Reseller ID'yi girin.

4) Sunucu IP Adresinin IP Whitelist'e Eklenmemiş Olması

Belirti: Kimlik bilgileri kontrol edilip doğrulandığı halde hata devam ediyor; özellikle yeni bir sunucuya taşındıktan veya Cloudflare/yük dengeleyici gibi bir katman eklendikten sonra başlamış.

Sebep: Reseller ID ve API Key panelinizde IP Whitelist özelliğiyle birlikte kullanılabilir. Whitelist aktifse ve isteğin geldiği IP listede değilse, kimlik bilgileri doğru olsa bile istek reddedilir.

Çözüm: Sunucunuzun güncel çıkış IP adresini Bayi Ayarları > Bayi Yapılandırmaları sekmesindeki IP Whitelist bölümüne ekleyin. Bu konuyu az sonra ekran görüntüleriyle adım adım gösteriyoruz.

5) Live / Test Ortam Karışıklığı

Belirti: Bazı istekler çalışıyor, bazıları Unauthorized dönüyor; veya entegrasyon test sırasında çalışıp canlıya geçince bozuluyor.

Sebep: Test Environment API Key ile Live ortam endpoint'ine (veya Live API Key ile Test ortamına) istek gönderilmesi, anahtarın kendisi geçerli olsa bile reddedilmesine yol açar.

Çözüm: Kullandığınız API Key'in hangi ortama ait olduğunu (Entegrasyon Bilgileri sayfasında Live/Test olarak ayrı ayrı listelenir) ve kodunuzdaki endpoint'in bu ortamla eşleştiğini doğrulayın.

Ekran Notu — Bayi Ayarları > Bayi Yapılandırmaları sekmesinde IP Whitelist bölümü. Kırmızı oklar sol menüdeki Bayi Ayarları girişini ve IP Whitelist bölümünün sayfadaki konumunu gösteriyor.

Bir IP'yi Listeden Kaldırma

Her IP satırının yanındaki çöp kutusu simgesine tıklayıp ardından Kaydet'e basarak ilgili IP'yi whitelist'ten çıkarabilirsiniz.

Netleştirilmesi Gereken Bir Nokta — Whitelist listesi tamamen boşken sistemin nasıl davrandığı (tüm IP'lere açık mı, yoksa hiçbir isteğe izin vermiyor mu) bu rehberin hazırlandığı kaynaklarda açıkça belirtilmiyor. Listenizi tamamen boşaltmadan önce bu davranışı destek ekibinize sorarak teyit etmenizi öneririz; aksi halde beklenmedik bir erişim kesintisi ya da güvenlik açığıyla karşılaşabilirsiniz.

6) Authorization Header'ın Eksik veya Yanlış Gönderilmesi

Belirti: İstek genel olarak doğru görünüyor, ama yine de kimlik doğrulama aşamasında reddediliyor.

Sebep: Birçok geliştirici, başka REST API'lerde sık kullanılan standart bir kalıbı (örneğin genel bir “Authorization” header şablonunu) doğrudan kopyalayıp buraya uygulamaya çalışır. Domain Name API'nin tam olarak hangi alanı header'da, hangi alanı istek gövdesinde beklediği, kullandığınız endpoint'e göre değişebilir.

Çözüm: Kendi hesabınıza ait kimlik bilgileriyle birebir eşleşen örnek isteği görmek için Production Swagger dokümantasyonını (api.domainresellerapi.com/swagger) veya Test/OT&E dokümantasyonını (ote.domainresellerapi.com/swagger) kontrol edin; bu dokümantasyon her endpoint için beklenen tam alan adlarını gösterir.

7) Genel REST Alışkanlığıyla Bearer Token Denemek

Belirti: Authorization: Bearer <token> şeklinde bir header eklediniz, ama hâlâ Unauthorized alıyorsunuz.

Sebep: Bearer token modeli birçok modern REST API'de standarttır, ama bu Domain Name API'nin kimlik doğrulama modeliyle aynı olduğu anlamına gelmez. Reseller ID ve API Key'in bekleneni biçimde (header, body veya query parametresi olarak — endpoint'e göre değişir) gönderilmesi gerekir; bunun yerine genel bir Bearer şablonu eklemek isteği değiştirmez, sadece gereksiz bir header eklemiş olursunuz.

Çözüm: Bearer şablonunu kaldırın; Swagger dokümantasyonundaki örnek isteği birebir takip edin.

❌ Yanlış (genel REST alışkanlığı):
Authorization: Bearer xxxxxxxxxxxxxxxx

✅ Doğru yaklaşım:
Swagger dokümantasyonunda (api.domainresellerapi.com/swagger) ilgili endpoint için gösterilen örnek isteği birebir kullanın.

8) Eski veya Güncellenmemiş Modül Sürümü

Belirti: WHMCS, WiseCP, HostBill, Blesta veya ClientExec üzerinden çalışıyorsunuz ve hata belirli bir güncellemeden sonra başladı (veya hiç güncelleme yapmadınız).

Sebep: Eski bir modül sürümü, kimlik bilgilerini API'nin artık beklemediği eski bir formatta veya eski bir parametre adıyla gönderebilir.

Çözüm: GitHub'daki domainreseller organizasyonundan (github.com/domainreseller) panelinize uygun modülün güncel sürümünü indirip kurun, ardından Reseller ID ve API Key'i yeniden kaydedin.

9) Kopyalama Hatası veya Görünmez Karakter

Belirti: Kimlik bilgileri “gözle bakınca doğru” görünüyor, ama hâlâ reddediliyor.

Sebep: API Key veya Reseller ID kopyalanırken başına/sonuna fazladan boşluk veya görünmez bir karakter eklenmesi, değeri görünüşte aynı ama sistem için geçersiz hale getirir.

Çözüm: Değeri panelden tekrar kopyalayıp doğrudan ilgili alana yapıştırın; şüpheniz varsa elle yeniden yazın.

10) Yanlış Content-Type Header

Belirti: İstek gövdesi doğru görünüyor, ama sunucu isteği hiç doğru ayrıştıramıyor (parse edemiyor) gibi davranıyor.

Sebep: REST API'lere JSON gövdeli istek gönderirken Content-Type header'ının uygulamanızın gönderdiği formatla eşleşmemesi (örneğin gövde JSON olduğu halde header'da application/x-www-form-urlencoded yazması), sunucunun isteği doğru şekilde işleyememesine ve kimlik bilgilerini hiç okuyamamasına yol açabilir.

Çözüm: HTTP istemcinizin gönderdiği gerçek Content-Type değerini bir ağ izleme aracıyla (örneğin tarayıcı geliştirici araçları veya Postman) doğrulayın ve Swagger dokümantasyonundaki beklenen değerle karşılaştırın.

# Reseller ID ve API Key'i kendi Swagger dokümantasyonunuzdaki
# alan adlarıyla değiştirin (header, body veya query parametresi olabilir)
curl -X POST "https://api.domainresellerapi.com/.../checkdomain" \
  -H "Content-Type: application/json" \
  -d '{
    "resellerId": "YOUR_RESELLER_ID",
    "apiKey": "YOUR_API_KEY",
    "domain": "exampledomain.com"
  }'

// Kimlik bilgilerini ortam değişkenlerinden okuyun, koda gömmeyin
$resellerId = getenv('DOMAINNAMEAPI_RESELLER_ID');
$apiKey     = getenv('DOMAINNAMEAPI_KEY');
 
// Alan adlarını kendi Swagger dokümantasyonunuzla teyit edin
$payload = [
    'resellerId' => $resellerId,
    'apiKey'     => $apiKey,
    'domain'     => 'exampledomain.com',
];
 
$response = $client->checkDomain($payload);

// Kimlik bilgilerini ortam değişkenlerinden veya güvenli bir
// secrets store'dan okuyun
var resellerId = Environment.GetEnvironmentVariable("DOMAINNAMEAPI_RESELLER_ID");
var apiKey     = Environment.GetEnvironmentVariable("DOMAINNAMEAPI_KEY");
 
// Alan adlarını ve gönderim şeklini (header/body) Swagger
// dokümantasyonunuzdan teyit edin
var payload = new {
    resellerId = resellerId,
    apiKey = apiKey,
    domain = "exampledomain.com"
};

// Kimlik bilgilerini .env dosyasından okuyun
const resellerId = process.env.DOMAINNAMEAPI_RESELLER_ID;
const apiKey = process.env.DOMAINNAMEAPI_KEY;
 
// Alan adlarını kendi Swagger dokümantasyonunuzla teyit edin
const payload = {
  resellerId,
  apiKey,
  domain: "exampledomain.com",
};

import os
 
# Kimlik bilgilerini ortam değişkenlerinden okuyun
reseller_id = os.environ.get("DOMAINNAMEAPI_RESELLER_ID")
api_key = os.environ.get("DOMAINNAMEAPI_KEY")
 
# Alan adlarını kendi Swagger dokümantasyonunuzla teyit edin
payload = {
    "resellerId": reseller_id,
    "apiKey": api_key,
    "domain": "exampledomain.com",
}

Anahtarınız Ele Geçirildiyse — Şüphelendiğiniz anda destek ekibiyle iletişime geçip anahtar yenileme (rotation) talep edin ve tüm uygulamalarınızı güncelleyin. Beklemek, riskin büyümesine neden olur.

401 Unauthorized hatasını neden alıyorum?

Bu hata, gönderdiğiniz Reseller ID ve API Key kombinasyonunun sistem tarafından geçerli kabul edilmediğini gösterir. En sık sebepler yanlış/eksik kimlik bilgileri, Reseller ID alanına e-posta yazılması ve sunucu IP'nizin Whitelist'te olmamasıdır.

401 ile 403 arasındaki fark nedir?

401, kimliğinizin doğrulanamadığını; 403 ise kimliğinizin doğrulandığını ama bu işlem için yetkiniz olmadığını gösterir. Domain Name API'de kimlik bilgisi sorunları pratikte 401 olarak görülür.

Bearer token kullanmalı mıyım?

Genel bir Bearer şablonu eklemek isteği değiştirmez. Reseller ID ve API Key'in beklenen biçimde gönderilmesi gerekir; bunun tam formatı endpoint'e göre Swagger dokümantasyonunda tanımlıdır.

API Key nasıl yenilenir?

Entegrasyon Bilgileri sayfasından mevcut anahtarı görüntüleyebilir, anahtarın ele geçirildiğini düşünüyorsanız destek ekibinizden yenileme (rotation) talep edebilirsiniz.

Reseller ID'mi nerede bulurum?

Hesabım > Bayi Ayarları > Entegrasyon Bilgileri sayfasında görüntülenir; “Bilgileri E-posta Gönder” butonuyla kayıtlı e-postanıza da gönderebilirsiniz.

IP Whitelist tamamen boş bırakılırsa ne olur?

Bu davranış kaynaklarımızda açıkça belirtilmiyor; boşaltmadan önce destek ekibinize sorup teyit almanızı öneririz.

Cloudflare kullanıyorsam hangi IP'yi eklemeliyim?

İsteğin Domain Name API'ye gerçekte hangi IP üzerinden ulaştığını kontrol etmeniz gerekir; bu, tarayıcınızda gördüğünüz IP'den farklı olabilir.

NAT arkasında bir sunucu kullanıyorum, ne yapmalıyım?

Whitelist'e eklemeniz gereken IP, sunucunun iç (private) IP'si değil, NAT'ın dışa açılan ortak (public) IP'sidir.

Load Balancer kullanıyorum, bu durumu etkiler mi?

Evet; isteğiniz yük dengeleyiciden çıkarken hangi genel IP'yi kullandığını belirleyip o IP'yi whitelist'e eklemeniz gerekir.

Shared hosting üzerinden çalışıyorum, IP Whitelist mümkün mü?

Mümkündür, ama paylaşımlı barındırmada genel çıkış IP'si sağlayıcınıza göre değişebilir veya paylaşılan olabilir; sağlayıcınızdan sunucunuzun sabit genel IP'sini teyit edin.

WHMCS modülüm neden çalışmıyor?

Aynı kök sebepler geçerlidir: yanlış Reseller ID/API Key, IP Whitelist eksikliği veya eski modül sürümü. Modülünüzü güncel sürüme yükseltip kimlik bilgilerini yeniden kaydedin.

WiseCP modülüm neden çalışmıyor?

WiseCP'de de aynı kimlik doğrulama mantığı geçerlidir; Reseller ID'nin kullanıcı adı alanına, API Key'in şifre alanına doğru girildiğinden emin olun.

Authentication Failed mesajı Unauthorized ile aynı mı?

Pratikte aynı kök nedene işaret eder: kimlik doğrulama başarısız olmuştur. Tam mesaj metni endpoint'e göre değişebilir, ama çözüm yaklaşımı aynıdır.

Unauthorized ile Invalid API Key aynı şey mi?

Yakından ilişkilidir ama aynı değildir. Invalid API Key spesifik olarak anahtarın geçersizliğine işaret eder; Unauthorized/Access Denied daha genel bir kimlik doğrulama reddini ifade edebilir (yanlış Reseller ID, IP Whitelist eksikliği gibi sebepleri de kapsar).

Test ortamında çalışan kod, canlıya geçince neden bozuluyor?

Genellikle Live ve Test ortam API Key'lerinin veya endpoint'lerinin karıştırılmasından kaynaklanır. Kullandığınız anahtarın ortamıyla endpoint'in eşleştiğini doğrulayın.

Modülümü güncellemek Reseller ID veya API Key'imi değiştirir mi?

Hayır. Modül güncellemesi sadece panel ile API arasındaki bağlantı katmanını günceller; kimlik bilgileriniz bu işlemden etkilenmez.

429 Too Many Requests, 401 Unauthorized ile aynı mı?

Hayır. 429, istek sıklığı limitini (saniyede 1 istek/API Key) aştığınızı gösterir; kimlik bilgilerinizle ilgisi yoktur. 401 ise kimlik doğrulama sorunudur.

Birden fazla sunucudan istek gönderiyorum, her birini whitelist'e eklemeli miyim?

Evet. IP Whitelist aktifse, istek gönderecek her sunucunun genel çıkış IP'sinin listede olması gerekir.

API Key'imi yanlışlıkla paylaştım, ne yapmalıyım?

Hemen destek ekibinizle iletişime geçip anahtar yenileme talep edin ve tüm uygulamalarınızı yeni anahtarla güncelleyin.

Sandbox ortamında test etmek zorunlu mu?

Zorunlu değil, ama şiddetle önerilir. Test ortamı gerçek kayıt oluşturmaz ve ücretlendirilmez; entegrasyonunuzu canlıya geçmeden güvenle doğrulamanızı sağlar.

Domain Name API REST API ile Güvenli Entegrasyon Yapın

• Ücretsiz bayi hesabı, aktivasyon ücreti veya minimum depozito şartı yok
• Sandbox (Test/OT&E) ortamında riske girmeden test edebilirsiniz
• REST API yanında WHMCS, WiseCP, HostBill, Blesta ve ClientExec için hazır modüller
• 200'den fazla ülkede 40.000'den fazla bayi tarafından kullanılan altyapı
• 7/24 teknik destek: ticket, telefon ve canlı destek

Entegrasyon sırasında herhangi bir sorunuz olursa teknik ekibimiz size yardımcı olmaktan memnuniyet duyar.

→ Ücretsiz bayi hesabınızı oluşturun 

→ Domain Bayilik Programı hakkında detaylı bilgi