Panel API
Herne'yi betikler, CI hatları ve ajanlarla otomatikleştirin — yetkinlik kapsamlı bearer anahtarlar, panelle aynı kural ve limitlere tabidir.
Panel API nedir
Panel API, tarayıcıdaki panelle aynı işlevleri CI işlem hatlarına, komut satırı araçlarına, operatör betiklerine, yapay zekâ ajanlarına ve üçüncü taraf entegrasyonlarına açar. Aynı işlem katmanını kullanır. Bir erişim anahtarı, sahibinin panelde sahip olduğu yetkileri aşamaz. Kiracı sınırları, plan kotaları, rol kontrolleri ve politikalar aynı biçimde uygulanır.
API, /panel/api altında bir durumsuz taşıyıcı-token yüzeyi olarak yaşamaktadır (oturma yoktur, CSRF yoktur). Bu, bu kurulumun güvenilir operatörleri için bir yönetim API'sidir, kamusal bir konumlandırma API'si değildir: anonim kayıt ve kendi kendini hizmet token çıkarma yoktur.
Erişim anahtarı oluşturma
Tokenler yalnızca panel UI'dan oluşturulur - hiçbir sanat komutu ve token yönetimi için API son noktası yoktur.
- Panel → API Erişim Anahtarları'e git.
- Bir isim girin (örneğin
ci-deploy) ve çağırıcının ihtiyacı olan özellikleri işaretleyin. Her grubun bir Hepsini seç tuşu vardır ve listenin üstündeki tuş tüm özellikleri aynı anda seçer. - Token Yarat'e tıklayın. Sade işaret (
hrn_ve ardından gelen 64 rastgele karakter) Tam olarak bir kez'te gösterilir — hemen kopyalayın. Sadece SHA-256 özet değeri depolanır.
Ekran size her iki istemci anahtarını birlikte verir, çağırıcınızın .env dosyasına veya CI gizli deposuna yapıştırmaya hazır:
HERNE_API_URL=https://your-server.example/panel/api
HERNE_API_TOKEN=hrn_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Kaybedilen erişim anahtarı geri alınamaz ve yeniden gösterilemez. Bu durumda anahtarı iptal edip yenisini oluşturun. Düzenleme yalnızca adı ve yetkileri değiştirir. Gizli anahtar değeri yenilenmez.
Yetki grupları
Yetenekler, güçlerine göre gruplandırılan düz noktalı resource.verb dizileridir:
- Öntanımlı — okunan yüzeyler artı günlük otomasyon (
sites.read,deploy.run,backups.read,me.read, ...). - Gelişmiş — opt-in yazma (
sites.write,databases.write,env.read/env.write,artisan.run, ...).env.readkasten yazma katmanı: site.envdosyaları kimlik bilgileri içerir. - Yıkıcı. — silme ve kabuk erişimi özellikle ayrı tutulur (
sites.delete,databases.delete,shell.run, …). Okuma işlemleri veriyi değiştirmez, yazma yetkileri silme yetkisi vermez ve silme işlemleri zincirleme yürütülmez. - Yönetici — admin-role-gated yüzeyler (
admin.users.read,admin.firewall.read, ...). Sadece admin'ler bunlara izin verebilir, ve sahibi hâlâ isteme zamanında admin rolü tutmalı.
Erişim anahtarı kullanma
Tokeni Authorization başlığında gönder — sadece taşıyıcı, sorgu-parametresi veya çerez geri dönüşü yok:
GET /panel/api HTTP/1.1
Host: your-server.example
Accept: application/json
Authorization: Bearer hrn_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Ya da kıvırcık:
curl -H "Authorization: Bearer $HERNE_API_TOKEN" $HERNE_API_URL/me
GET /panel/api keşif son noktasıdır: bir işaret olmadan, kamu güvenliği için güvenli bir bootstrap JSON geri döndürür; bir işaretle, ayrıca becerilerinizin ulaşabileceği kaynakları da bağlar.
Yanıtlar
Başarı cevapları üst düzey alan anahtarlarıyla ok-ilk düz JSON'dur:
{"ok": true, "site": {"slug": "example-com", "domain": "example.com"}}
Hatalar şekli paylaşırlar, sabit bir makine code ekler ve her zaman kendi keşif bağlantılarını taşırlar:
{
"ok": false,
"code": "missing_capability",
"message": "This token does not have the sites.write capability.",
"api_discovery_url": "/panel/api",
"openapi_url": "/panel/api/openapi.json"
}
HTTP durum kodlarının kullanımı: 200 okuma veya güncelleme, 201 oluşturma, 401 eksik, geçersiz veya iptal edilmiş erişim belirteci, 403 eksik yetki veya başarısız ilke denetimi, 404 bilinmeyen ya da başka bir hesaba ait kaynak, 422 doğrulama hatası, 429 istek sınırının aşılması. Doğrulama hataları errors[] alanında {path, message} nesneleri olarak listelenir.
İstek sınırları
API, ip|token başına dakikada 120 isteğe izin verir. Daha maliyetli uç noktalar ayrıca paneldeki daha sıkı sınırları uygular. Dakikada en fazla 10 dağıtım, 5 geri yükleme, 20 Artisan isteği, 60 kabuk isteği ve 5 panel güncellemesi yapılabilir.
Güvenlik notları
- Erişim anahtarının açık değeri oluşturulurken bir kez gösterilir ve saklanmaz. Yalnızca SHA-256 özeti saklanır.
- Bir işareti geri çekmek onun isteklerini derhal reddedecektir; satır denetim için tutulur. Silmek satırı ve onun faaliyet geçmişini siler.
- Yönetici becerileri, talepte tekrar kontrol edilir: token çıkarılmasından sonra iptal edilen bir rol onları derhal etkisiz hale getirir.
shell.runvarsayılan yetki kümelerinin hiçbirine dahil değildir. Açıkça seçilmesi gerekir ve panel terminaliyle aynı siteye özel, yalıtılmış kabuk ortamını kullanır.- Her anahtarın son etkinliği, yöntem, yol, izin sonucu ve IP adresiyle API Erişim Anahtarları ekranında görünür. İstek gövdeleri ve erişim anahtarının içeriği hiçbir zaman günlüklere yazılmaz.
Kapsam
Panelin sunduğu her eylem, alan adları ve dış yönlendirme, Laravel çalıştırma dönüşümü, disk kullanımı güncellemesi, log kesimi, veritabanı başına ihraç dosyaları, yedekleme boyutu tahminleri, veritabanı tarayıcıları, faturalar, yardım konuları ve kendi profiliniz dahil olmak üzere bir API son noktasına sahiptir. Üç şey tasarıma göre sadece panelde kalır: API token yönetiminin kendisi, webmail ve kimlik doğrulama akış (login, kayıt, şifre yeniden oluşturma, e-posta doğrulama). Kurulum sihirbazının kendi son noktası yoktur - her adımı ayrı bir API primitifidir.
OpenAPI
Runtime tarafından oluşturulan OpenAPI 3.1 belgesi GET /panel/api/openapi.json adresinde mevcuttur (token gereklidir). Tam son nokta ve şema yüzeyi için istemci üreticisi veya ajan araçlarınızı ona yönlendirin.