Cloud API

Kendi barındırdığınız bir Alaf Server örneğini Alaf Server Cloud'a ve onu destekleyen bulut kontrol düzlemi uç noktalarına (handoff, edge proxy, pages, subgraph transfer, GitHub App proxy) bağlayın.

Cloud API, kendi barındırdığınız bir Alaf Server örneğini Alaf Server Cloud'a (yönetilen kontrol düzlemi) bağlar, böylece bulut çalışma zamanlarına deploy edebilir, yönetilen domain'leri ve sayfaları kullanabilir ve merkezi GitHub App'i ödünç alabilir. İki ayrı yarıya sahiptir ve hangisinin monte edileceği işlem moduna bağlıdır:

Kendi barındırılan set (cloud-local) — connect/disconnect, status ve workspaces/drift listelemesi. Yalnızca örnek bulut modunda değilken monte edilir. Kendi kutunuzda çağırdığınız şey budur.
Bulut kontrol düzlemi seti (cloud-saas) — handoff/OAuth, namespace token minting, edge-proxy/pages/analytics proxy'leri, subgraph transfer ve GitHub App proxy'si. Yalnızca bulut modunda (CLOUD_MODE) monte edilir. Kendi barındırdığınız örneğiniz, depolanan bulut oturumu üzerinden bunları makineden makineye çağırır; bunları nadiren elle çağırırsınız.

Her iki yarı da /api/cloud temel yolunu paylaşır, ancak herhangi bir işlemde yalnızca biri bulunur.

Temel yol ve kimlik doğrulama

Tüm yollar, örneğin https://your-host/api/cloud/status gibi, örneğinize göre /api altında yer alır. Kendi barındırılan uç noktalar, bir bearer header olarak kişisel bir erişim token'ı alır (Authorization: Bearer <token>, alaf server token create komutundan); dashboard oturum çerezinizi kullanır. Bulut kontrol düzlemi uç noktaları, connect sırasında oluşturulan bulut oturum bearer'ı ile (veya genel handoff rotaları için URL'deki imzalı tek kullanımlık bir token ile) kimlik doğrulaması yapar — kendi barındırılan bir PAT ile değil. API genel bakışına ve kimlik doğrulama modeline bakın.

Kendi barındırılan uç noktalar

Yalnızca kendi barındırılan bir örnekte bulunur (CLOUD_MODE modunda değil). Bulut bağlantısı kuruluşa aittir: kuruluş sahibine aittir, bu nedenle her üye aynı kararı görür. Disconnect ve connect-finalize işlemleri yalnızca cloud:admin izni değil, owner rolünü gerektirir.

Metot ve yol	İzin	Ne işe yarar
`GET /api/cloud/status`	`cloud:read`	Bu örnek için Alaf Server Cloud bağlantı durumu.
`GET /api/cloud/workspaces`	`cloud:read`	Kuruluşun Alaf Server Cloud (Mtntasci) workspaces'lerini, drift (yetim bulut/yerel) ile birlikte listeler.
`POST /api/cloud/connect-finalize`	`cloud:admin` + owner	Connect popup'ını tamamlar: PKCE kodunu takas eder ve bulut bearer'ını depolar.
`POST /api/cloud/disconnect`	`cloud:admin` + owner	Kuruluşun depolanan bulut oturumunu temizler ve üye GitHub izinlerini budar.

Bağlantı durumunu kontrol et

GET /api/cloud/status

curl https://your-host/api/cloud/status \
  -H "Authorization: Bearer $ALAFSERVER_TOKEN"

# CLI, aynı bağlantı durumunu status çıktısında gösterir:
alaf server status

Bağlantı kurma işlemi, dashboard'dan (Ayarlar → Cloud) başlatılan bir tarayıcı akışıdır: bir popup, Alaf Server Cloud'a karşı PKCE handshake'ini çalıştırır, ardından sonucu aşağıdaki connect-finalize adresine gönderir. Özel bir alaf server cloud connect CLI komutu yoktur.

Bir bağlantıyı sonlandır

Dashboard popup'ı PKCE doğrulayıcısını localStorage'dan okur ve kuruluşun bulut bearer'ını depolamak için döndürülen kodu buraya gönderir.

POST /api/cloud/connect-finalize

Prop

Type

Yalnızca sahip

connect-finalize ve disconnect kuruluşun bulut bearer'ını devraldığı için, cloud:admin etiketine ek olarak requireRole("owner") ile korunurlar. cloud:admin iznine sahip bir sahip olmayan kullanıcı yine de 403 alır.

Bulut kontrol düzlemi uç noktaları

Yalnızca bulut modunda (CLOUD_MODE) bulunur — yani bunlar Alaf Server Cloud üzerinde çalışır, kendi barındırdığınız kutunuzda değil. Tüm kiracı kapsamlı işlemler, çağıranın namespace token'ı aracılığıyla Mtntasci'ye iletilir; Mtntasci namespace sınırını yerel olarak uygular, bu nedenle SaaS tarafında bir sahiplik defteri yoktur. public rotaları oturum taşımaz — bunlara tarayıcı yönlendirmeleriyle ulaşılır ve URL'deki imzalı, tek kullanımlık bir token ile kimlik doğrulaması yapılır.

Metot ve yol	İzin	Ne işe yarar
`GET /api/cloud/desktop-handoff`	public	OAuth → tek kullanımlık kod → masaüstü uygulama callback'ine yönlendirme.
`GET /api/cloud/connect-handoff`	public	Bağlantı parametrelerini doğrular, ardından dashboard onay sayfasına 302 yönlendirmesi yapar.
`POST /api/cloud/connect-authorize`	public	Onay sayfası tek kullanımlık bir handoff kodu oluşturur (çerez oturumu satır içi kontrol edilir).
`POST /api/cloud/exchange-code`	public	Kullanıcı + oturum için tek kullanımlık bir kodu takas eder (rate-limited).
`POST /api/cloud/token`	`cloud:write`	Çağıranın kuruluşu için namespace kapsamlı bir Mtntasci token'ı oluşturur.
`GET /api/cloud/account`	`cloud:read`	Bağlı bulut hesabı (ad, e-posta, avatar).
`POST /api/cloud/disconnect`	`cloud:admin`	Mevcut bulut oturumunu sunucu tarafında iptal eder (idempotent).
`POST /api/cloud/preflight`	`cloud:write`	Bulut deploy preflight — slug / custom-domain kullanılabilirliği.
`POST /api/cloud/edge-proxy`	`cloud:write`	Yönetilen edge proxy'yi senkronize eder (bir slug'ı bir hedefe bağlar).
`POST /api/cloud/analytics`	`cloud:write`	Çağıranın namespace'indeki bir hostname için Mtntasci analytics'i proxy eder.
`POST /api/cloud/pages`	`cloud:write`	Bir Cloud Page oluşturur (Mtntasci `pages.create` proxy eder).
`POST /api/cloud/pages/enable`	`cloud:write`	Bir Cloud Page'i slug ile etkinleştirir.
`POST /api/cloud/pages/disable`	`cloud:write`	Bir Cloud Page'i slug ile devre dışı bırakır.
`POST /api/cloud/pages/delete`	`cloud:write`	Bir Cloud Page'i slug ile siler.
`POST /api/cloud/send-invitation`	`cloud:write`	SaaS mail altyapısı aracılığıyla bir davet e-postasını iletir.
`POST /api/cloud/ingest-subgraph`	`cloud:admin`	Kuruluş veya proje kapsamlı bir subgraph dump'ını alır (rate-limited, 50MB sınırı).
`POST /api/cloud/export-subgraph`	`cloud:admin`	Kuruluş veya proje kapsamlı bir subgraph dump'ını dışa aktarır (rate-limited).
`POST /api/cloud/teardown-project`	`cloud:admin`	Bir projenin SaaS üzerindeki satırlarını siler (bring-home / reconcile).
`POST /api/cloud/github/oauth-handoff`	`cloud:write`	GitHub OAuth'ı başlatır: tek kullanımlık bir köprü URL'si döndürür.
`GET /api/cloud/github/oauth-bridge`	public	Köprü token'ını tüketir ve tarayıcıyı GitHub OAuth'a yönlendirir.
`GET /api/cloud/github/oauth-success`	public	Dostça "GitHub bağlandı" pencere kapatma sayfası.
`POST /api/cloud/github/install-url`	`cloud:write`	Tek kullanımlık bir durum token'ı ile App kurulum URL'sini oluşturur.
`GET /api/cloud/github/install-callback`	public	GitHub kurulum callback'i — kurulumu başlatan kullanıcıya atfeder.
`GET /api/cloud/github/installations`	`cloud:read`	Kuruluş sahibinin GitHub App kurulumlarını listeler.
`POST /api/cloud/github/installation-token`	`cloud:write`	Kısa ömürlü (~60dk) bir kurulum erişim token'ı oluşturur.
`GET /api/cloud/github/user-status`	`cloud:read`	Çağıran için bulut tarafından çözümlenmiş GitHub OAuth kimliği (login, avatar).

Bunlar çoğunlukla dahili

Kendi barındırdığınız örneğiniz, bulut istemcisi aracılığıyla kontrol düzlemi uç noktalarını sizin için çağırır — bunları elle bağlamazsınız ve bunlara birebir eşleşen bir alaf server CLI komutu yoktur. Aşağıdaki istek şekilleri, entegratörlerin trafiği anlamlandırabilmesi için belgelenmiştir.

Handoff ve kod değişimi

Connect ve masaüstü login akışları yerel örneğe asla bir tarayıcı çerezi vermez. Bunun yerine, kısa ömürlü, PKCE'ye bağlı bir handoff kodu oluşturulur (connect-authorize), ardından özel bir oturumla (exchange-code) değiştirilir.

POST /api/cloud/connect-authorize

Prop

Type

POST /api/cloud/exchange-code

Prop

Type

Genel GET handoff rotaları bir body yerine sorgu parametreleri alır — desktop-handoff ve connect-handoff redirect, state ve code_challenge bekler; github/install-callback installation_id, setup_action ve state bekler; github/oauth-bridge token bekler.

Deploy proxy'leri (preflight, edge proxy, analytics)

POST /api/cloud/preflight

Prop

Type

POST /api/cloud/edge-proxy

Prop

Type

POST /api/cloud/analytics

Prop

Type

Sayfalar

pages yönetilen bir statik sayfa oluşturur; etkinleştirme/devre dışı bırakma/silme eylemlerinin her biri yalnızca bir slug alır.

POST /api/cloud/pages

Prop

Type

POST /api/cloud/pages/disable   (also /enable, /delete)

Prop

Type

Davetiye iletimi

Kendi barındırılan bir operatör invitationMailSource = "cloud" olarak ayarladığında kullanılır — SaaS e-postayı kendi altyapısından gönderir. Hizmet içinde kuruluş başına saatte 20 ile sınırlıdır.

POST /api/cloud/send-invitation

Prop

Type

Subgraph transfer ve kaldırma

Ingest/export çifti, bir kuruluşun veya tek bir projenin satırlarını kendi barındırılan bir örnek ile SaaS arasında taşır (ekip modu geçişi ve proje transferi). Örnek kapsamlı dump'lar reddedilir.

POST /api/cloud/ingest-subgraph

Prop

Type

POST /api/cloud/export-subgraph

Prop

Type

POST /api/cloud/teardown-project

Prop

Type

GitHub App proxy'si

Cloud, GitHub App özel anahtarını tutar; kendi barındırılan örnekler asla tutmaz. Yerel, (userId, request)'i devreder ve çözümlenmiş verileri geri alır — asla bir JWT imzalamaz veya App kimlik bilgilerini görmez.

POST /api/cloud/github/installation-token

Prop

Type

installationId asla body'den kabul edilmez

installation-token kurulumu çağıranın kuruluşundan çözer, istemci tarafından sağlanan bir id'den değil — bir id geçmek hiçbir etki yaratmaz. Bu, bir çağıranın sahip olmadığı bir kurulum için token oluşturmasını engeller.

Görebileceğiniz hatalar

403 — sahip gerekli (kendi barındırılan connect/disconnect)

connect-finalize ve disconnect kuruluş owner rolünü gerektirir. Yalnızca cloud:admin iznine sahip bir üye reddedilir.

409 — slug zaten alınmış (edge proxy / pages)

İstenen slug, paylaşılan bulut bölgesindeki başka bir kiracıya aittir. Mtntasci 409 döndürür ve Alaf Server bunu iletir. Farklı bir slug seçin.

412 — dump format uyuşmazlığı (ingest)

ingest-subgraph, formatVersion'ı SaaS ile eşleşmeyen dump'ları reddeder (code: INGEST_FORMAT_MISMATCH). Yerel örneğinizi güncelleyin ve yeniden dump yapın.

413 — dump çok büyük (ingest)

ingest-subgraph, kimlik doğrulama çalışmadan önce istek body'sini 50MB ile sınırlar (code: PAYLOAD_TOO_LARGE).

401 — geçersiz veya süresi dolmuş kod / oturum

Handoff kodları tek kullanımlık ve zaman sınırlıdır; exchange-code tüketildiğinde veya süresi dolduğunda 401 döndürür. Kontrol düzlemi cloud:* uç noktaları, bulut oturum bearer'ı eksik veya iptal edildiğinde 401 döndürür — dashboard'dan yeniden bağlanın.

On this page