API Token'ları

Granüler izinler, zaman sınırlı erişim ve hazır izin gruplarıyla UptimeWarden API token'ları oluşturun, kapsamlandırın, döndürün ve iptal edin.

UptimeWarden API'si script'lerden, CI hatlarından, dashboard'lardan, CLI'dan ve üçüncü taraf entegrasyonlardan kullanılır. Tek bir tam yetkili anahtar pratiktir ama tehlikelidir, sızdığında saldırgana her şey açılır. UptimeWarden bunu granüler, izin kapsamlı token'lar ve en hassas okumalarda yerleşik zaman sınırları ile çözer.

Token formatı

Token uzun ve rastgele bir karakter dizisidir:

32 rastgele bayt, base64url ile kodlanmış.
uptw_ ön ekiyle başlar; loglarda kolayca tanınır.
İlk 12 karakter (örn. uptw_abcd123) referans verebileceğiniz açık ön ek olarak saklanır; geri kalanı hash'lenir ve oluşturma sonrası asla geri alınamaz.

Ön ek; token yönetim ekranında, denetim kayıtlarında ve kullanım raporlarında görünen kısımdır. Böylece secret'i sızdırmadan hangi token'ın ne yaptığını görebilirsiniz.

İzin modeli

İzinler <kaynak>:<aksiyon> biçimindedir. Her token bir izin listesi taşır; her istekte API, token'ın endpoint'in gerektirdiği izne sahip olup olmadığını kontrol eder.

Monitor izinleri

İzin	Erişim	Sınır
`monitors:read`	Monitor'ları ve durumlarını listele	Yok
`monitors:create`	Yeni monitor oluştur	Abonelik monitor sınırı
`monitors:delete`	Monitor sil	Yok
`monitors:results:read`	Kontrol sonuçlarını ve istatistikleri oku	7 gün geçmişle sınırlı

Olay (incident) izinleri

İzin	Erişim	Sınır
`incidents:read`	Olayları listele	30 gün geçmişle sınırlı
`incidents:update`	Durum / çözüm güncelle	Yok
`incidents:comment`	Zaman çizelgesine yorum ekle	Yok

SSL izinleri

İzin	Erişim	Sınır
`ssl:status:read`	SSL sertifika durumunu oku	Yok

Güvenlik analizi izinleri

İzin	Erişim	Sınır
`security:analysis:read`	Önbelleklenmiş analiz sonuçlarını oku	Yok
`security:analysis:monitor`	Sahip olunan monitor'larda analiz çalıştır	10 istek/dk
`security:analysis:website`	Herhangi bir URL'de analiz çalıştır	10 istek/dk

Sağlık tahmini izinleri

İzin	Erişim	Sınır
`health:predictions:read`	AI sağlık tahminlerini oku	Yalnızca sahip olunan monitor'lar

Deploy ve bakım izinleri

CI/CD hatları için (örn. GitHub Actions deploy bildirimleri):

İzin	Erişim	Sınır
`deploys:read`	Zaman çizelgesindeki deploy işaretçilerini listele ve incele	Yok
`deploys:write`	Deploy işaretçilerini kaydet ve sonlandır	Yok
`monitors:maintenance:read`	Sahip olunan monitor'lardaki aktif bakım pencerelerini listele	Yok
`monitors:maintenance:write`	Sahip olunan monitor'larda bakım (susturma) penceresi aç ve kapat	Yok

Admin izni

İzin	Erişim	Sınır
`admin`	Her v1 endpoint'ine tam erişim	Yok

admin'i acil durum otomasyonu için saklayın. CI token'ları her zaman bir preset ile kapsamlandırılmalı.

Hazır izin grupları

Token oluşturma diyaloğu, başlangıç noktası olarak kullanabileceğiniz tek tıkla preset'ler sunar:

Grup	Kullanım	İzinler
Monitor Viewer	Salt okunur dashboard, durum gösterimi	`monitors:read`, `monitors:results:read`, `ssl:status:read`
Monitor Manager	Infrastructure-as-code, otomatik provisioning	+ `monitors:create`, `monitors:delete`
Incident Manager	Bilet entegrasyonu, on-call otomasyonu	`incidents:read`, `incidents:update`, `incidents:comment`
Security Analyst	Uyumluluk taraması, güvenlik denetimi	`security:analysis:read`, `security:analysis:monitor`, `security:analysis:website`, `ssl:status:read`
Health Monitor	AI tahmin tüketicileri	`monitors:read`, `health:predictions:read`
Deploy Manager	CI/CD deploy işaretçileri ve susturma pencereleri	`monitors:read`, `deploys:read`, `deploys:write`, `monitors:maintenance:read`, `monitors:maintenance:write`
Full Access	Dahili araçlar, acil durum	Yukarıdakilerin tümü

Preset seçtikten sonra token oluşturmadan önce izin ekleyebilir veya çıkarabilirsiniz.

Zaman sınırlı izinler

İki izin, her istekte uygulanan yerleşik bir zaman sınırı taşır:

monitors:results:read, en fazla 7 gün geçmiş.
incidents:read, en fazla 30 gün geçmiş.

Daha geniş bir pencere istemek 403 TIME_RANGE_EXCEEDED döner; istenen ve izin verilen değerler details içinde yer alır. Bu sınırlar planınızın veri saklama ayarından bağımsızdır, daha geniş pencere için dashboard'u kullanın.

Token oluşturma

Dashboard'a giriş yapın.
API Portal → API Tokens sekmesini açın.
Create API Token'a tıklayın.
Şunları ayarlayın:
- İsim: kendi referansınız için bir etiket (örn. GitHub Actions deploy pipeline).
- İzinler: bir preset seçin veya manuel olarak oluşturun.
- Süre sonu (opsiyonel): "asla dolmaz" için boş bırakın; rotasyonu zorlamak için tarih belirleyin.
Create'e tıklayın ve token'ı diyalogdan kopyalayın. Diyalog kapandığında secret kalıcı olarak kaybolur.

Kimlik doğrulama

Token'ı Authorization header'ında gönderin:

GET /api/v1/monitors
Authorization: Bearer uptw_abcd1234...

Bearer ön eki zorunludur. Ham token veya query-string ile kimlik doğrulama reddedilir.

Kullanımı görüntüleme

Token ile yapılan her API çağrısı kaydedilir: endpoint, HTTP metodu, durum kodu, yanıt süresi, user agent ve IP adresi. Dashboard token başına kullanımı gösterir; hatalı davranan entegrasyonları yakalamak ve aniden tanıdık olmayan endpoint'lere atan sızmış token'ları tespit etmek için kullanın. Varsayılan görünüm son 30 gündür.

Token döndürme

"Rotate" butonu yoktur, silip yeniden oluşturursunuz, ideal olarak çakışmayla:

Aynı izinlerle yeni bir token oluşturun.
Yeni token'ı tüm tüketicilere dağıtın.
Eski token'ın kullanımının sıfıra düştüğünü gözleyin.
Eski token'ı silin.

Bu çakışma tek nokta arızasını önler. Token sızdığı için anında döndürmeniz gerekiyorsa hemen silin ve yeni token dağıtılana kadar kısa bir kesintiyi kabul edin.

Token iptali

DELETE /api/user/api-tokens/:id token'ı kaldırır. Devam eden istekler tamamlanır; o token ile bir sonraki istek 401 Unauthorized döner. Sızdığını fark ettiğiniz token'ları aynı gün silin.

Denetim izi

Token oluşturma, izin değişikliği ve silme işlemleri; aktör, token'ın açık ön eki ve zaman damgasıyla birlikte denetim kaydına yazılır. Tam liste için Denetim Günlükleri sayfasına bakın.

Sınırlar

Kullanıcı başına aktif token sayısı planınız tarafından belirlenir.
Dakikalık hız limitleri token başına uygulanır; sınırlar endpoint ailesine göre değişir, bkz. API Endpoint'leri.
Hesabınıza ayrı bir aylık API çağrı sınırı uygulanır. Aşıldığında 403 MONTHLY_API_LIMIT_EXCEEDED döner.

SSS

Bir token'ı birden fazla servis arasında paylaşabilir miyim? Teknik olarak evet, ama önermiyoruz. Servis başına token kullanmak bağımsız döndürme ve iptal sağlar; her token'ın tek tüketicisi olduğunda kullanım panosu çok daha faydalıdır.

Token "Forbidden" diyor ama çalışması gerektiğini düşünüyorum. Hata yanıtı eksik izni belirtir. İzni API Endpoint'leri referansıyla karşılaştırın.

Token planımın sınırlarını taşır mı? Evet, sınırlar token seviyesinde değil hesap seviyesinde uygulanır. Token'larınızdan herhangi biriyle yapılan monitor oluşturma isteği, aboneliğinizin monitor sınırından düşer.

Endpoint ve izinlerin makineyle okunabilir listesi nerede? /api/docs/v1-openapi.json, kanonik OpenAPI 3.0 spec'i.

İlgili

Denetim Günlükleri: token kullanımı hakkında neler kayıt altına alınır
Abonelik Planları: plan başına token ve çağrı sınırları
API Hızlı Başlangıç: token ile ilk curl çağrısı
API Endpoint'leri: endpoint başına gereken izin