Unipile Hosted Auth nedir?

Unipile tarafından barındırılan ve kullanıcınızın kendi sağlayıcısında kimlik doğruladığı bir sayfa. Bağlantıyı POST /v2/auth/link ile oluşturur, kullanıcıyı bu bağlantıya yönlendirir ve karşılığında bir account_id alırsınız. Kimlik bilgileri ve token'lar asla kodunuzdan geçmez.

Hosted Auth bağlantısını hangi endpoint oluşturur?

POST https://api.unipile.com/v2/auth/link, X-API-KEY başlığıyla ve providers, expires_on ve redirect_uri içeren bir body ile. v2'de /v2/hosted/accounts/link diye bir yol yoktur.

Kullanıcının bağlanmayı tamamladığını nasıl anlarım?

İki kanal üzerinden. redirect_uri adresi account_id, provider ve state değerlerini query parametresi olarak alır. account.add webhook olayı aynı state değerini taşır. Doğruluk kaynağı olarak webhook'u, kullanıcı deneyimi için yönlendirmeyi kullanın.

Sihirbazda hangi sağlayıcıları gösterebilirim?

providers şunları kabul eder: *, bir aile filtresi (örneğin *:EMAILS, *:MESSAGING, *:CALENDAR veya *:SOCIAL) ya da linkedin, whatsapp, google, outlook, imap, telegram ve instagram arasından bir liste. Akışı test etmek için mock kullanın.

Unipile MCP · Hosted Auth

Unipile Hosted Auth, kodlama ajanınız tarafından uygulanır

Q: Çalışmayı durduran bir hesabı nasıl yeniden bağlarım?

Aynı endpoint, providers yerine account_id ile. Sözleşmeye göre hesabın tamamı yenilenir ve yapılandırılmış tüm ürünler yeniden başlar. Akışı account.status.disconnected olayından veya hesap durumundan tetikleyin.

Kullanıcılarınız kendi LinkedIn, WhatsApp veya e-posta hesaplarını Unipile'ın barındırdığı bir sayfada bağlar. Unipile MCP sunucusu sayesinde rotayı ve callback'i ajanınız yazar.

Hosted Auth'u bir ajanla uygulayın Hosted Auth dokümantasyonu

7 gün ücretsiz deneme, kredi kartı gerekmez.

Bu React ve Fastify uygulamasına Unipile Hosted Auth'u uygula.

Endpoint okunuyorPOST /v2/auth/linkşema yüklendi

Bağlantı rotası ve callback eklendi. Account ID çalışma alanına kaydediliyor.

4 dosya değişti · providers: "mock" ile test edildi

Sonraki özelliği anlatın…

İş

Yapmak istediğiniz şey

Ürününüzün her kullanıcısının, kodunuz hiçbir şifre veya token görmeden kendi hesaplarını bağlamasını sağlamak ve sonraki her isteğin ihtiyaç duyduğu account ID'yi geri almak. Her sağlayıcının kendi giriş ekranı, iki adımlı doğrulaması ve onay ekranı vardır. Hosted Auth bunların hepsini Unipile'ın sunduğu tek bir sayfada toplar; ajan da uygulamanıza ait üç parçayı birbirine bağlar.

Onsuz Giriş formları, token'lar, sağlayıcı tuhaflıkları

Her sağlayıcı için bir giriş formu yazar ve tutmak istemediğiniz token'ları saklarsınız.

İki adımlı doğrulama istemleri ve onay ekranları akışı her sağlayıcıda farklı şekilde bozar.

Account ID yönlendirmeden tahmin edilmeye çalışılır ve kullanıcı sekmeyi kapatınca kaybolur.

Unipile MCP sunucusuyla Uygulamanızdaki sonuç

Barındırılan sihirbazı açan bir Bağlan butonu ve account ID'yi çalışma alanına kaydeden bir callback rotası.

Kayıtlı account ID ile aynı endpoint'i yeniden kullanan bir Yeniden bağlan butonu.

Gerçek bir hesap bağlanmadan önce Development uygulamanızda mock sağlayıcıyla doğrulanmış akış.

Prompt, adımlar, kod

Ajanınıza prompt'u verin

İki prompt; her birinde ajanın okuyup çalıştırdığı Unipile endpoint'leri ve projenize eklenenler yer alır. Yollar eksiksiz verilmiştir; API temel URL'si: https://api.unipile.com, Scope'a bağlı anahtarınız ise X-API-KEY başlığında.

Ajanınız · crm-appDevelopment uygulaması

Bu React ve Fastify uygulamasına Unipile Hosted Auth'u uygula: auth bağlantısını oluşturan bir sunucu rotası, account_id ve state değerlerini okuyan bir callback rotası ve account_id'nin mevcut çalışma alanında saklanması.

Endpoint okunuyorPOST /v2/auth/linkşema yüklendi

İstek çalıştırılıyorPOST /v2/auth/link201 · link

Eklendi: POST /api/accounts/connect (Fastify): auth link endpoint'ini şu değerlerle çağırır: providers, bir expires_on (ISO 8601 UTC biçiminde, on beş dakika sonrası), callback'in redirect_uri adresi ve çalışma alanı ID'sini taşıyan imzalı bir state değeri. Ardından React Ayarlar sayfası yanıttaki adresi açar: link. GET /auth/callback ise account_id, provider ve state değerlerini query'den okuyup hesabı kaydeder. Development uygulamasında providers: "mock" ile test edildi.4 dosya değişti · bağlantı akışı uçtan uca test edildi

Sunucu tarafında oluşturulan bir bağlantı, account ID'yi kaydeden bir callback

Bağlantı sunucunuzda, Scope'a bağlı anahtarınızla oluşturulur; tarayıcı yalnızca barındırılan URL'yi alır. Kullanıcı işini bitirdiğinde Unipile onu redirect_uri adresinize yönlendirir; query string'de account_id, provider ve sizin state yer alır. Ajan bu üç alanı ezberden değil sözleşmeden okur ve callback'i buna göre yazar.

Ajanın kullandığı endpoint'ler

POST/v2/auth/linkGET/v2/accounts/{account_id}GET/v2/accounts/

Sık yapılan hata: Auth bağlantısını tarayıcıdan oluşturmak. Anahtar sızar; frontend yalnızca sunucunuzun döndürdüğü bağlantıyı açar.

Auth link referansı

Ajanınız · crm-appDevelopment uygulaması

Bağlı her hesabın yanına bir Yeniden bağlan butonu ekle: kayıtlı account_id ile Unipile auth link endpoint'ini yeniden kimlik doğrulama modunda çağır ve callback'i ilk bağlantıdaki gibi işle.

Endpoint okunuyorPOST /v2/auth/linkyeniden kimlik doğrulama dalı

İstek çalıştırılıyorGET /v2/accounts/{account_id}status: disconnected

Eklendi: POST /api/accounts/:id/reconnect: aynı endpoint, aynı redirect_uri, ancak body account_id alanını taşır, artık providers yok. Ayarlar sayfası, hesap durumu running değilken butonu gösterir; dönüşü mevcut callback karşılar. Development uygulamasında mock hesabın bağlantısı kesilerek doğrulandı.2 dosya değişti · ilk bağlantı callback'ini yeniden kullanır

Aynı endpoint, tek bir alan değişir

Yeniden bağlanma bağlantısı account_id alır, şunu almaz: providers; ilk bağlantı ise providers alır, şunu almaz: account_id. Sözleşmeye göre hesabın tamamı yenilenir ve yapılandırılmış her ürün yeniden başlar; bu yüzden ajan bunu hesap durumundan tetikler ve iki akış için tek callback kullanır.

Ajanın kullandığı endpoint'ler

POST/v2/auth/linkGET/v2/accounts/{account_id}POST/v2/auth/checkpoint

Sık yapılan hata: Hem providers hem account_id göndermek. Body ya bir dalı ya da diğerini içerir, asla ikisini birden değil.

account.status.disconnected ile tetikleyin

Payload

İstek body'si, iki dal ve yanıt

Ajanın sunucu üzerinden okuduğu v2 sözleşmesinden birebir. İlk bağlantı için üç alan zorunludur ve yanıt tek bir bağlantıdır.

1Yeni bir hesap bağlamaproviders, expires_on ve redirect_uri zorunludur. state, yönlendirmede ve account.add olayında aynen geri döner. account_scope_id hesabı bir Scope'a atar.POST https://api.unipile.com/v2/auth/link { "providers": "*", "expires_on": "2026-10-01T12:00:00.000Z", "redirect_uri": "https://app.example.com/auth/callback", "state": "ws_42.signed", "account_scope_id": "scope_…" }

2Mevcut bir hesabın kimliğini yeniden doğrulamaaccount_id, providers alanının yerini alır. Hesabın tamamı yenilenir ve yapılandırılmış her ürün yeniden başlar.POST https://api.unipile.com/v2/auth/link { "account_id": "acc_…", "expires_on": "2026-10-01T12:00:00.000Z", "redirect_uri": "https://app.example.com/auth/callback" }

3Yanıt ve dönüşYanıt bir HostedAuthLink'tir. Sihirbazdan sonra yönlendirme account_id, provider ve state taşır; account.add webhook'u da aynı state değerini taşır.{ "object": "HostedAuthLink", "link": "https://auth.unipile.com/…" } GET https://app.example.com/auth/callback?account_id=acc_…&provider=linkedin&state=ws_42.signed

Development'tan production'a

Önce bir Development uygulamasında test edin

Unipile panelinizde Development uygulaması Production'dan ayrıdır. Ajana Development'tan Scope'a bağlı bir anahtar verin ve mock sağlayıcıyı kullanın: akışın tamamı, gerçek hesap olmadan.

1Akışı providers: "mock" ile çalıştırınBağlantı sunucu tarafında oluşturuldu, callback okundu, account ID kaydedildi.

2Test hesabını yeniden bağlayınBağlantısını kesin, yeniden bağlanma bağlantısını açın, durum tekrar running olur.

3account.add'i doğrulayın, ardından anahtarı değiştirinWebhook, yönlendirmeyle aynı state değerini taşır; ancak bundan sonra Production'ı kullanın.

crm-app · DevelopmentAjanınız tarafından kullanılır

Scopedev-tests · 2 hesap

AnahtarScope'a bağlı Account API anahtarı

HesaplarLinkedIn test hesabı, Gmail test posta kutusu

Webhook'lar1 endpoint · mesaj olayları

crm-app · ProductionDokunulmaz

Scopeçalışma alanı başına bir tane

AnahtarScope'a bağlı anahtarlar, yalnızca backend'inizde

Hesaplarkullanıcılarınızın kendi hesapları, Hosted Auth ile

Sorun giderme

Sık görülen hatalar ve anlamları

Bir Hosted Auth entegrasyonunu durduran dört hata ve her birinin çözümü. Çoğu bir v1 örneğini kopyalamaktan kaynaklanır.

Body'de notify_url veya success_redirect_url

İstek reddedilir ya da callback hiç tetiklenmez. ÇözümBunlar v1 alanlarıdır. v2 body'si şunları alır: redirect_uri ve state; bildirimler ise şu olaylara abone bir webhook endpoint'i üzerinden gelir: account.add ve account.reconnect.

expires_on reddedildi

Tarihte doğrulama hatası. ÇözümAlan ISO 8601 UTC biçiminde bir tarih-saat bekler: YYYY-MM-DDTHH:MM:SS.sssZ. Unix zaman damgası veya yerel tarih kabul edilmez.

Tek body'de iki dal

providers veya account_id üzerinde doğrulama hatası. Çözümİlk bağlantı providers alır, şunu almaz: account_id; yeniden bağlanma ise account_id alır, şunu almaz: providers. Tek bir dal gönderin.

Account ID hiç gelmiyor

Kullanıcı yönlendirmeden önce sekmeyi kapattı. ÇözümYönlendirme yalnızca bir kolaylıktır. Doğruluk kaynağı, webhook endpoint'inize gelen account.add olayıdır; bu olay aynı state değerini taşır. Kaydı olaydan yapın, yönlendirmeyle teyit edin.

6000+ Unipile ile inovasyon yapan şirketler

Sektör liderlerinin tercihi

1 API

Tüm büyük iletişim kanallarında operasyonları sadeleştirin

2 Gün

Minimum kurulumla hızla canlı entegrasyona geçin

30%

Bakım çabası ve kaynaklarında azalma

Yerleşik güvenlik ve uyumluluk

Verileriniz ve iş akışlarınız için kurumsal düzeyde koruma Güvenliğimiz hakkında daha fazla bilgi

SOC 2 Type II

Sertifikalı

Veri korumasını ve operasyonel bütünlüğü güvence altına alan, bağımsız olarak denetlenmiş güvenlik kontrolleri.

GDPR

Uyumlu

Kullanıcı gizliliği için Avrupa veri koruma düzenlemelerine tam uyum.

99.9%

Son 24 aydaki platform çalışma süresi

24/7

Yüksek performanslı API ile küresel destek

Hosted Auth SSS

Hosted Auth nedir, bağlantıyı hangi endpoint oluşturur, kullanıcının işlemi bitirdiğini nasıl anlarsınız, nasıl yeniden bağlanılır ve sihirbaz hangi sağlayıcıları gösterebilir.

Unipile tarafından barındırılan ve kullanıcınızın kendi sağlayıcısında kimlik doğruladığı bir sayfa. Bağlantıyı şu çağrıyla oluşturursunuz: POST /v2/auth/link, kullanıcıyı bu bağlantıya yönlendirirsiniz ve karşılığında bir account_id alırsınız. Kimlik bilgileri ve token'lar asla kodunuzdan geçmez.

POST https://api.unipile.com/v2/auth/link, çağrıda X-API-KEY başlığı bulunur, body ise şunları içerir: providers, expires_on ve redirect_uri. v2'de /v2/hosted/accounts/link diye bir yol yoktur.

İki kanal üzerinden. İlki: redirect_uri adresi account_id, provider ve state değerlerini query parametresi olarak alır. İkincisi: account.add webhook olayı aynı state değerini taşır. Doğruluk kaynağı olarak webhook'u, kullanıcı deneyimi için yönlendirmeyi kullanın.

Aynı endpoint; body account_id alanını taşır, artık providers yok. Sözleşmeye göre hesabın tamamı yenilenir ve yapılandırılmış tüm ürünler yeniden başlar. Akışı account.status.disconnected olayından veya hesap durumundan tetikleyin.

providers şunları kabul eder: *, bir aile filtresi (örneğin *:EMAILS, *:MESSAGING, *:CALENDAR veya *:SOCIAL) ya da şu değerlerden oluşan bir liste: linkedin, whatsapp, google, outlook, imap, telegram ve instagram. Akışı test etmek için mock kullanın.