Kimlik Doğrulama

Güncellendi 19 Kas 2026 Markdown

Her istek HMAC-SHA256 kimlik doğrulama header'larını taşımalıdır. İmzalanan payload kanonik hale getirilir; bu sayede yakalanmış bir imza farklı bir endpoint'e, gövdeye veya zaman penceresine karşı tekrar oynatılamaz.

X-WHost-KeyAPI anahtarı kimliği (/admin/api-keys üzerinden yapılandırılabilir).
X-WHost-TimestampMevcut Unix zaman damgası (saniye).
X-WHost-Nonce16–256 karakter, istek başına benzersiz (öneri 32 hex); tekrar edilen nonce reddedilir.
X-WHost-SignatureHMAC-SHA256(api_secret, "METHOD\nPATH\nTIMESTAMP\nNONCE\nBODY") hex digest.

Agent şu isteklerini reddeder:

  • zaman damgası 300 saniyeden eski olan,
  • nonce'u tekrar penceresi içinde (300 sn zaman damgası toleransının iki katı + 60 sn) zaten görülmüş olan,
  • imzası sunucu tarafında yeniden hesaplandığında eşleşmeyen,
  • path'i posixpath.normpath ve matrix-param sıyırma sonrası imzalanan path'ten kayan (böylece sondaki ;foo=bar path bağlamasını atlayamaz).

Hesaba bağlı (bayi) anahtarlar

Bir bayi hesabının client panelden (Settings → API Access) ürettiği anahtar istekleri sunucu anahtarıyla birebir aynı şekilde imzalar, ancak o bayi olarak sunulur: yalnızca /api/v1/client/* yüzeyine ulaşır ve orada bayinin sahiplik kontrolleri ve ACL planıyla çalışır. Böyle bir anahtarın aldığı yanıtlar:

İstek Yanıt
/api/v1/client/ dışındaki herhangi bir yol 403 SCOPE_DENIED
/api/v1/client/api-keys*, /api/v1/client/profile* (kimlik bilgisi ve profil yönetimi) 403 HMAC_FORBIDDEN_FOR_CREDENTIAL_MUTATION — yalnızca tarayıcı oturumu
Bayinin sahibi olmadığı bir alt hesap 404 ACCOUNT_NOT_FOUND
Bayinin ACL planında api_access yok ya da hesap artık bayi değil 403 PERMISSION_DENIED
Sahip hesap askıda, sonlandırılmış ya da silinmiş; anahtar iptal edilmiş 401 AUTH_FAILED

Anahtarın kapsamı sabittir (client) ve genişletilemez; bir bayi en fazla 10 anahtar tutar. Bayinin kendi anahtarları için yönetim uçları: GET/POST /api/v1/client/api-keys, PUT /api/v1/client/api-keys/{key_id}, POST /api/v1/client/api-keys/{key_id}/revoke, DELETE /api/v1/client/api-keys/{key_id}, GET /api/v1/client/api-keys/logs — yalnızca oturum çerezi ile. Yönetici tüm anahtarları GET /api/v1/system/api-keys altında görür; owner alanı bayiyi adlandırır (sunucu geneli anahtarlarda null).

Kanonik imzalama payload'ı (v2)

metin
METHOD\nPATH\nTIMESTAMP\nNONCE\nBODY

PATH, agent tarafından görünen path'tir (host'tan sonraki kısım, /api/v1/... prefix'i dahil). BODY, surrogateescape ile UTF-8 olarak decode edilmiş ham HTTP gövde byte'larıdır (ikili yüklemeler yeniden encode etmeye gerek kalmadan imzalanabilir).

Referans Python imzalayıcı

Python
import hashlib, hmac, json, secrets, time
from urllib.request import Request, urlopen
import ssl

API_KEY    = "your-api-key"
API_SECRET = "your-api-secret"
BASE_URL   = "https://panel.example.com"

def sign(method: str, path: str, body: bytes = b"") -> dict[str, str]:
    ts    = str(int(time.time()))
    nonce = secrets.token_hex(16)
    body_str = body.decode("utf-8", errors="surrogateescape")
    payload  = f"{method}\n{path}\n{ts}\n{nonce}\n{body_str}"
    sig = hmac.new(
        API_SECRET.encode("utf-8"),
        payload.encode("utf-8", errors="surrogateescape"),
        hashlib.sha256,
    ).hexdigest()
    return {
        "X-WHost-Key":       API_KEY,
        "X-WHost-Timestamp": ts,
        "X-WHost-Nonce":     nonce,
        "X-WHost-Signature": sig,
        "Content-Type":      "application/json",
    }

body = json.dumps({"username": "alice"}).encode("utf-8")
headers = sign("POST", "/api/v1/accounts", body)
req = Request(f"{BASE_URL}/api/v1/accounts", data=body,
              headers=headers, method="POST")
ctx = ssl.create_default_context()
ctx.check_hostname = False
ctx.verify_mode = ssl.CERT_NONE  # üretimde kaldırın
print(urlopen(req, context=ctx).read())

Diğer dillerdeki imzalayıcılar bu dosyanın yanında bulunur:

Yönetici oturum çerezi (yalnızca tarayıcı)

/admin/* paneli ve /client/* paneli, POST /api/v1/auth/login (ardından 2FA etkinleştirildiğinde /api/v1/auth/login/2fa) üzerinden httpOnly bir oturum çerezi üretir. SDK'lar ve partner entegrasyonları her zaman bunun yerine HMAC kullanmalıdır — oturumlar tarayıcı bağlamına özgüdür ve her yetki değişikliğinde rotasyona girer.

Parola değişikliği (faturalama anahtarları)

PATCH /api/v1/accounts/{username}/password (gövde {"password": "…"}) hesabın panel parolasını, sistem kullanıcısının ve varsayılan FTP kullanıcısının parolasını değiştirir. API anahtarıyla sunucu geneli, tam erişimli bir anahtar gerekir — API Erişimi sayfasındaki her Tam Erişim anahtarı, kurucunun Default API Key'i dahil ("scopes": ["*", "billing"] ile oluşturulmuş anahtarlar da aynı çalışır). Tam erişimi olmayan anahtar 403 SCOPE_DENIED alır. Parola kuralları paneldeki gibidir (en az 8 karakter, en çok 72 bayt; 422 VALIDATION_ERROR). Denetim günlüğü değişikliği aktörü anahtar olarak kaydeder. Burada yapılan değişiklik (faturalama anahtarıyla ya da yönetici oturumuyla) hesabın açık müşteri paneli oturumlarını kapatır — müşterinin kendi oturumu, hatırlanan oturum ve yöneticinin "müşteri olarak giriş" oturumu; müşteri yeni parolayla yeniden giriş yapar.

Müşteri giriş bağlantıları (faturalama sistemleri)

Bir faturalama sistemi müşterisini parola girmeden WHost müşteri paneline POST /api/v1/accounts/{username}/login-token ile sokar (yalnız API anahtarı; paneldeki yönetici bunun yerine müşteri olarak oturum açmayı kullanır). Gövde, her alan isteğe bağlı: ip — müşterinin adresi, bağlantı yalnız o adresten çalışır; ttl — saniye, 10–300, varsayılan 60; lang — açılacak panel dili. Yanıttaki login_url panel adresine görelidir: müşterinin tarayıcısını https://<panel adresi><login_url> adresine gönderin.

  • Bağlantı /api/v1/auth/client/login-link#token=<jeton> biçimindedir. Jeton # işaretinden sonra taşınır; tarayıcı bu kısmı sunucuya hiç göndermez: jeton web sunucusunun ve CDN'in erişim kayıtlarına, sonraki sayfanın Referer başlığına düşmez. Bağlantının açtığı sayfa jetonu okur, adres çubuğundan siler ve POST /api/v1/auth/client/login-token ucuna (form alanı token) gönderir. Adresi olduğu gibi açın: yönlendirme (Location:) # kısmını korur, o kısım atılarak yeniden kurulan adres giriş sayfasına düşer.

  • Önceki biçim GET /api/v1/auth/client/login-token?token=<jeton> 1.x hattında giriş yaptırmaya devam eder ve kullanımdan kalkıyor: WHost bu biçimi artık üretmez, ajanın kendi erişim kaydı jetonunu *** olarak yazar.

  • İlk ziyaret sonucu ne olursa olsun bağlantıyı tüketir; bilinmeyen, kullanılmış ya da süresi dolmuş bağlantı, bağlandığı adresten başka bir adres ya da artık etkin olmayan hesap oturumsuz olarak müşteri giriş sayfasına düşer.

  • Oturum müşterinin kendi oturumudur (müşteri olarak oturum açma şeridi yok) ve parolayla girişte olduğu gibi hesabın öteki müşteri oturumlarını kapatır. Bağlantı hesabın ikinci adımını atlar: müşteriyi faturalama sistemi doğrulamıştır.

  • Askıdaki hesap 403 ACCOUNT_SUSPENDED; yönetici oturumu 403 PERMISSION_DENIED; hesaba bağlı ya da kısıtlı anahtar 403 SCOPE_DENIED alır.

  • Bağlantılar ajanın belleğinde durur: ajan yeniden başlarsa kullanılmamış olanlar düşer. X-Idempotency-Key ile tekrar istekte login_url "***" döner — yeni bir bağlantı oluşturun.

Müşterinin phpMyAdmin girişi (faturalama sistemleri)

GET /api/v1/accounts/{username}/databases/phpmyadmin-url (tam erişimli API anahtarı ya da yönetici oturumu) hesabın müşterisi için phpMyAdmin açar: beş dakika yaşayan ve yalnız o hesabın kendi veritabanlarına yetkili bir MariaDB kullanıcısı için tek kullanımlık jeton — müşteri panelindeki phpMyAdmin düğmesinin açtığı oturumun aynısı, sunucunun root'u asla. ?db=<kısa ad> (ya da tam <kullanıcı>_<ad>) o veritabanını açar. Yanıt {"login_url": "/phpmyadmin/whost_sso.php?token=…[&db=…]"} olup panel adresine görelidir; müşterinin tarayıcısını oraya gönderin.

  • Veritabanı olmayan hesap ya da hesabın sahip olmadığı bir db, herhangi bir MariaDB kullanıcısı oluşturulmadan 404 DATABASE_NOT_FOUND alır; başka bir hesabın veritabanı adı bu hesabın içindeki bir ad olarak okunur.
  • Kullanılmış jeton giriş sayfasında 401 alır. MariaDB kullanıcısı jeton oluşturulduktan beş dakika sonra, kullanılsın ya da kullanılmasın silinir; bu phpMyAdmin oturumunu da bitirir: her ziyaret için yeni adres oluşturun.
  • Kısıtlı ya da hesaba bağlı anahtar 403 SCOPE_DENIED alır; phpMyAdmin kurulu olmayan sunucu 200 ve error_code: PMA_NOT_INSTALLED döndürür.
  • Veritabanı başına uç GET /accounts/{username}/databases/{db_name}/phpmyadmin-url root olarak oturum açmaya devam eder; adresini müşteriye vermeyin.

Hesap IP engelleri

/api/v1/accounts/{username}/firewall/ip-blocks (tam erişimli API anahtarı ya da yönetici oturumu) hesabın kendi engel listesidir: listedeki adres o hesabın her web sitesinde 403 alır, başka hiçbir yerde değil — liste hesabın vhost'larına yazılır, sunucu güvenlik duvarına asla. Müşteri panelinin Güvenlik Duvarı sayfası aynı listeyi /api/v1/client/firewall/ip-blocks üzerinden yönetir (müşterinin oturumu ya da kendi hesabı için hesaba bağlı anahtar).

  • GET → [{"id","ip","comment","created_at"}].
  • POST {"ip": "<adres ya da ağ>", "comment": "<isteğe bağlı, ≤ 255>"} — tek bir IPv4 / IPv6 adresi ya da /16'dan (IPv4) veya /48'den (IPv6) geniş olmayan bir ağ; 203.0.113.9/24 203.0.113.0/24 olarak saklanır. Listede zaten olan adres 200 ve değişiklik yok döndürür. Belirsiz, çok noktaya yayın, bağlantı-yerel ve /0 değerleri, daha geniş ağ, notta denetim karakteri ve bilinmeyen alan 422 VALIDATION_ERROR alır; hesap başına en çok 500 kayıt.
  • DELETE …/ip-blocks/{ip} — listelendiği biçimde, URL kodlu (203.0.113.0%2F24); listede olmayan adres 404 NOT_FOUND alır.
  • Her yazma hesabın bütün vhost'larını yeniden üretir ve yapılandırmayı sınar; web sunucusunun reddettiği yapılandırmada önceki liste kalır (500 VHOST_CONFIG_ERROR). OpenLiteSpeed / LiteSpeed sunucuları 409 FEATURE_DISABLED döndürür.
  • Adres, web sunucusunun gördüğü ziyaretçi adresidir (Cloudflare arkasında gerçek ziyaretçi adresi). ACME doğrulama yolu erişilebilir kalır ve bir yönlendirme kuralı (return) engelden önce yanıtlanır.
  • Denetim günlüğü scope: account ile firewall_ip_blocked / firewall_ip_unblocked yazar. Eski /accounts/{username}/firewall/blocked-ips uçları değişmedi: sunucu güvenlik duvarına yazarlar (scope: server).
Hâlâ Yardıma mı İhtiyacınız Var?

Yukarıda bulamadığınız her şey için destek ekibimiz her zaman yanınızda.