Kapsule Orbit API Tokenleri ve REST API

API tokens let a script, a CI pipeline or your own tooling drive Orbit without a browser session: trigger deployments, report CI check results, download build artifacts, manage cron jobs and more…

API tokenleri, bir betik, bir CI işlem hattı veya kendi araçlarınızın Orbit'i tarayıcı oturumu olmadan kullanmasını sağlar: dağıtımları tetikleyin, CI kontrol sonuçlarını bildirin, derleme yapıtlarını indirin, cron işlerini yönetin ve daha fazlasını, hepsi kendi kapsamını belirlediğiniz Bearer token ile kimlik doğrulaması yaparak.

Tokenler Nerede Bulunur

Orbit'i açın ve üst düzey gezintiden Tokens seçeneğini seçin. Sayfa API Access Tokens başlığını taşır ve kuralını baştan belirtir: tokenler oluşturulduğu anda bir kez gösterilir.

Tam endpoint belgesi bir tıkla uzakta. API Reference kartında, Orbit'in her endpoint'i için panel içi referansı açan bir View docs düğmesi vardır.

API Access Tokens page in Orbit

Token Oluşturma

New token seçeneğini tıklayın.
Buna bir Token name verin. Bunu onu kullanacak şeyin adından sonra adlandırın, örneğin CI iş akışı, böylece envanter daha sonra okunabilir olur.
Scopes seçeneğini seçin.
İsteğe bağlı olarak bir Expiry ayarlayın. Süresi dolmayan bir token için boş bırakın.
Create token seçeneğini tıklayın.

Ham token, One-time reveal başlığı altında bir kopya düğmesiyle bir kez görüntülenir. Doğrudan CI gizli dizi deposuna yapıştırın. Bunu tekrar görmek için bir yol yoktur: sadece tokenin SHA-256 karması saklanır, bu nedenle Kapsule bile onu sizin için kurtaramaz.

Bir hesap en fazla 20 aktif token tutabilir. Yirmi birincisi oluşturmak reddedilir ve önce mevcut bir tokeni iptal etmeniz gerektiğini söyleyen bir mesaj görüntülenir.

Hiçbir zaman tokeni sohbet mesajına, bilete, commit'e veya ekran görüntüsüne yapıştırmayın. deploy:write olan bir token kodu üretime gönderebilir ve env:write olan bir token ortam yapılandırmanızı okuyabilir ve değiştirebilir. Bunu tam olarak bir parola gibi ele alın.

Kapsamlar

Kapsamlar tokenin tüm amacıdır: her biri sadece verdiğiniz izinleri taşır.

Kapsam	İzin Verir
`deploy:write`	Dağıtımları tetikleyin ve yönetin
`project:read`	Proje ve ortam ayrıntılarını okuyun
`project:write`	Proje ayarlarını değiştirin
`env:read`	Ortam değişkeni meta verilerini okuyun
`env:write`	Ortam değişkenlerini ayarlayın ve silin

Yeni bir token varsayılan olarak deploy:write ve project:read ile gelir, bu da bir dağıtım işlem hattının ihtiyaç duyduğu ve başka hiçbir şeyin olmadığıdır.

İşi yapan en küçük seti verin. Sadece CI sonucunu bildirmesi gereken bir token'e project:write gerekli değildir. Salt okunur bir izleme betiği yazma kapsamına da ihtiyaç duymaz. Referanstaki her endpoint, gerektirdiği minimum kapsamı listeler.

Token Kullanma

Kimlik doğrulama, API tabanına karşı bir Bearer başlığıdır: https://kapsulehost.com:

curl -X POST https://kapsulehost.com/api/orbit/$ORBIT_PROJECT_ID/deployments \
  -H "Authorization: Bearer $ORBIT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"branch":"main"}'

Tokens sayfası hazır bir CI/CD usage snippet'i ve bir GitHub Actions starter iş akışını taşır. Başlatıcı .github/workflows/orbit-deploy.yml olarak kaydedilir ve iki depo sırrını gerektirir: ORBIT_TOKEN ve ORBIT_PROJECT_ID. Her ikisini de sayfadan kopyalayın, yazarak aktarmayın.

API'nin Kapsamı

Panel içi referans, her alanı parametreleri ve gerekli kapsamı ile belgelendirmektedir:

Deployments: bir dağıtım tetikleyin, isteğe bağlı olarak adlandırılmış bir dalda, isteğe bağlı olarak beş dakika ile otuz gün arasında gelecek bir zaman için planlanmış, 500 karaktere kadar bir notla. Listeleme, commit, mesaj, dal ve yazar arasında bulanık aramayı destekler, ayrıca dal, durum ve ortamda filtreleme yapılır, imleç sayfalandırması sayfa başına 100 sonuca kadar.
Deployment checks: CI işinizin başında bir kalite kontrolü kaydedin, sonra tamamlandığında sonucu bildirin. Başarısız olan bir required kontrol dağıtımı FAILED'e taşır ve ortamı önceki başarılı dağıtıma geri döndürür, bu da kendi test paketinizi gerçek bir dağıtım kontrolü haline getirmenizin yoludur.
Branch protection: gerekli kontroller geçene ve isteğe bağlı olarak birisi onaylanana kadar otomatik dağıtımları engelleyen glob deseni kuralları. Proje başına en fazla on kural.
Build artifacts: başarılı bir dağıtımın derlenmiş çıktısı için önceden imzalanmış bir indirme URL'si alın. URL on beş dakika için geçerlidir.
Project transfer: başka bir hesaba transfer başlatın, iptal edin ve durumunu kontrol edin. Bkz. Transferring an Orbit Project.
Cron jobs: listeleyin, oluşturun, güncelleyin, silin, tetikleyin ve yürütme geçmişini okuyun. Bkz. Orbit Cron Jobs.
Timeline annotations: olay, sürüm, kilometre taşı, not ve bayrak ek açıklamalarını oluşturun ve yönetin. Bkz. Orbit Timeline Annotations.
Status page: genel durum sayfası yapılandırmasını okuyun ve yazın. Bkz. Orbit Status Page.
Edge functions: kenar işleyicilerini listeleyin, oluşturun, güncelleyin ve dağıtın. Bkz. Orbit Edge Functions.

Panelden oturum kimlik doğrulaması Bearer tokenler ile yan yana çalışır, bu nedenle tarayıcınızdan çağırabileceğiniz bir endpoint genellikle bir betikten de çağrılabilir.

Turbo Remote Cache

Tokens sayfası ayrıca bir Remote Build Cache kartı taşır. Turborepo Remote Cache Protocol'ü uygular ve bir monorepo'nun CI çalışmaları ve geliştirici makineleri arasında derleme önbelleklerini paylaşmasını sağlar.

Kartında etkinleştirin, oluşturduğu tokeni kopyalayın ve bunu hesap kimliğinizle birlikte CI ortamınızda TURBO_TEAM olarak ayarlayın. 150 MB'a kadar yapıtlar kabul edilir. Kart ayrıca Rotate token ve Disable seçeneği sunar.

Monorepo'nuzun CI'ı zamanının çoğunu değişmemiş paketleri yeniden derlemekte harcarsa, bu sayfadaki en yüksek değerli tek şeydir.

Envanterin Yönetilmesi

Token inventory, her aktif tokeni şu bilgilerle listeler:

Ne zaman Created (Oluşturuldu).
Ne zaman Last used (Son Kullanıldı) veya Never (Asla).
Ne zaman Expires (Sona Eriyor), süresi dolduktan sonra bir expired (Süresi Doldı) rozetiyle.

Last used sütunu denetlenecek olan sütundur. Hiçbir zaman kullanılmamış bir token ya yanlış yapılandırılmıştır ya da unutulmuştur ve her iki durumda da hiçbir şey yapmayan bir kimlik bilgisidir. Sayfanın kendi ipucu bunu açıkça söyler: tanımadığınız her şeyi iptal edin.

Token'i İptal Etme

Satırda iptal kontrolünü tıklayın. Onay açıktır: bu token ile kimlik doğrulayan her şey hemen erişimini kaybeder ve bu geri alınamaz.

Bir işlem hattı kullanımdan kaldırıldığında, CI sırlarına erişimi olan birisi ayrıldığında veya bir tokenin sızdığını şüphelendiğiniz anda iptal edin. Kısmi iptal yoktur ve uyuşmazlık süresi yoktur, bu da sızıntı durumunda tam olarak istediğiniz şeydir.

Tek seferlik bir iş için oluşturduğunuz tokenlere bir süre sonu belirleyin. Süresi dolan bir token kendini temizler; iki günlük bir geçiş için oluşturulan kalıcı bir token iki yıl sonra hala geçerlidir.

Sorun Giderme

401 Unauthorized (401 Yetkisiz). Başlık yanlış veya token iptal edilmiş veya süresi dolmuş. Başlığın Authorization: Bearer <token> olduğunu, tek bir boşluk ile ve CI gizli dizisinin sondaki yeni satıra sahip olmadığını kontrol edin.

403 Forbidden (403 Yasak). Token geçerlidir ancak bu endpoint için kapsamdan yoksundur. Referans endpoint başına minimum kapsamı listeler. Kapsamlar oluşturma sırasında sabitlenmiştir, bu nedenle doğru seti olan yeni bir token oluşturun.

429 on creation (Oluşturma sırasında 429). Yirmi tokenin limitine ulaştınız. Envanterde bir şeyi iptal edin.

The artifact URL stops working (Yapıt URL'si çalışmayı durdurdu). Önceden imzalanmış URL'ler on beş dakika sürer. URL'yi depolamak yerine yeni bir URL talep edin.

A scheduled deployment is rejected (Planlanmış bir dağıtım reddedilir). Planlanmış zaman gelecekte beş dakika ile otuz gün arasında olmalıdır.

Sonraki Adımlar

Deploying Your Project: tetiklenen dağıtımın aslında ne yaptığını görmek için.
Orbit Deployment Pipeline: API dağıtımlarınızın hangi kontrolleri karşılayacağını görmek için.
Orbit Plan Limits: planınızın neleri içerdiğini öğrenmek için.