Kimlik Doğrulama
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.normpathve matrix-param sıyırma sonrası imzalanan path'ten kayan (böylece sondaki;foo=barpath 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)
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ı
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:
- PHP —
docs/developer/examples/hmac-example.php - JavaScript / Node.js —
docs/developer/examples/hmac-example.js - Go —
docs/developer/examples/hmac-example.go - Ruby —
docs/developer/examples/hmac-example.rb - Bash / POSIX sh —
docs/developer/examples/hmac-example.sh
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ınRefererbaşlığına düşmez. Bağlantının açtığı sayfa jetonu okur, adres çubuğundan siler vePOST /api/v1/auth/client/login-tokenucuna (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 oturumu403 PERMISSION_DENIED; hesaba bağlı ya da kısıtlı anahtar403 SCOPE_DENIEDalır. -
Bağlantılar ajanın belleğinde durur: ajan yeniden başlarsa kullanılmamış olanlar düşer.
X-Idempotency-Keyile tekrar istektelogin_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şturulmadan404 DATABASE_NOT_FOUNDalır; başka bir hesabın veritabanı adı bu hesabın içindeki bir ad olarak okunur. - Kullanılmış jeton giriş sayfasında
401alı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_DENIEDalır; phpMyAdmin kurulu olmayan sunucu200veerror_code: PMA_NOT_INSTALLEDdöndürür. - Veritabanı başına uç
GET /accounts/{username}/databases/{db_name}/phpmyadmin-urlroot 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/24203.0.113.0/24olarak saklanır. Listede zaten olan adres200ve değişiklik yok döndürür. Belirsiz, çok noktaya yayın, bağlantı-yerel ve/0değerleri, daha geniş ağ, notta denetim karakteri ve bilinmeyen alan422 VALIDATION_ERRORalı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 adres404 NOT_FOUNDalı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_DISABLEDdö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: accountilefirewall_ip_blocked/firewall_ip_unblockedyazar. Eski/accounts/{username}/firewall/blocked-ipsuçları değişmedi: sunucu güvenlik duvarına yazarlar (scope: server).
Yukarıda bulamadığınız her şey için destek ekibimiz her zaman yanınızda.