OAuth ile bir iş ortağı uygulaması kaydedin ve yüklü uygulamaları yönetin

Bir OAuth uygulaması, diğer Flowella kuruluşlarının API anahtarlarını paylaşmadan ürününüzü kendi hesaplarına bağlamasını sağlar. Her kuruluş uygulamanızı bir onay ekranında onaylar ve istediği zaman iptal edebilir. Bu sayfa, iş ortaklarına bir uygulamanın nasıl kaydedileceğini ve OAuth’un nasıl kullanılacağını, müşterilere ise yükledikleri uygulamaları nasıl inceleyip iptal edeceklerini gösterir. Kendi betikleriniz ve entegrasyonlarınız için bir API anahtarı daha basittir.

Nasıl çalışır

Flowella üç OAuth izin türünü destekler: müşterilerin kuruluşları için PKCE ile yetkilendirme kodu, kendi kuruluşunuz için istemci kimlik bilgileri ve yenileme belirteçleri. Sıra diyagramı, bir müşterinin yetkilendirme kodu izin türüyle uygulamanızı nasıl yüklediğini gösterir.

Başlamadan önce

Uygulamanın sahibi olacak kuruluşta Owner veya Admin rolüne ihtiyacınız vardır. Diğer roller menüde Developer apps öğesini görebilir, ancak liste onlar için yüklenmez.
Uygulamanızın yetkilendirme kodunu alabilecek bir geri çağırma adresine (yönlendirme URI’si) ihtiyacı vardır.
Uygulamanız her yetkilendirme isteğinde bir state değeri ve S256 ile oluşturulmuş bir PKCE code_challenge göndermelidir.

Bir uygulama kaydedin

Developer apps sayfasını açın

Settings bölümüne gidin, ardından Developer grubunda Developer apps seçeneğini seçin.

Yeni bir uygulama başlatın

Create app seçeneğini seçin. Create developer app iletişim kutusu açılır.

Uygulamayı adlandırın

App name alanına müşterilerin ürününüzü tanıdığı adı en fazla 120 karakterle girin, örneğin Acme CRM connector.

Yönlendirme URI'leri ekleyin

Redirect URIs alanına her geri çağırma adresini ayrı bir satıra, en fazla 20 adet olacak şekilde girin. Yetkilendirme sırasında uygulamanızın gönderdiği redirect_uri bunlardan biriyle tam olarak eşleşmelidir.

Kapsamları seçin

Scopes altında okuma kapsamları sizin için işaretlenmiştir. Uygulamanızın ihtiyaç duyduğu diğer kapsamları işaretleyin ve ihtiyaç duymadıklarının işaretini kaldırın. Bunlar uygulamanızın isteyebileceği en geniş kapsamlardır. Bkz. Kapsamlar.

Uygulamayı oluşturun ve sırrı kopyalayın

Create app seçeneğini seçin. Save your client secret iletişim kutusu, flc_ ile başlayan istemci sırrını gösterir. Copy seçeneğini seçin, sırrı sunucunuzda saklayın, ardından Done seçeneğini seçin.

Flowella istemci sırrını yalnızca bir kez gösterir ve sırrı sıfırlayamazsınız. Kaybederseniz uygulamayı silmeniz ve yeni bir uygulama kaydetmeniz gerekir; uygulamanızı kullanan her kuruluşun da yenisini onaylaması gerekir.

Bir uygulamanın adını, yönlendirme URI’lerini veya kapsamlarını oluşturduktan sonra değiştiremezsiniz. Bunları değiştirmek için yeni bir uygulama kaydedin. Developer apps listesi her uygulamanın Name, Client ID (floa_ ile başlar), Redirect URIs ve Created tarihini, Actions altında bir Delete düğmesiyle birlikte gösterir.

Bir müşteriyi yetkilendirmeden geçirin

Müşterinin tarayıcısını Flowella uygulama sunucusundaki yetkilendirme uç noktasına gönderin:

https://app.flowella.io/api/oauth/authorize?response_type=code&client_id=floa_xxxx&redirect_uri=https%3A%2F%2Fexample.com%2Foauth%2Fcallback&scope=messages%3Aread%20contacts%3Aread&state=RANDOM_STATE&code_challenge=CODE_CHALLENGE&code_challenge_method=S256

Parametre	Zorunlu	Değer
`response_type`	Evet	`code`
`client_id`	Evet	Uygulamanızın istemci kimliği.
`redirect_uri`	Evet	Uygulamanın kayıtlı yönlendirme URI’lerinden biri, birebir.
`state`	Evet	Müşteri geri geldiğinde uygulamanızın kontrol ettiği rastgele bir değer.
`code_challenge`	Evet	Uygulamanızın sakladığı rastgele bir `code_verifier` değerinin base64url ile kodlanmış SHA-256 hash’i.
`code_challenge_method`	Hayır	Desteklenen tek yöntem ve varsayılan olan `S256`.
`scope`	Hayır	Boşluklarla ayrılmış, tümü uygulamanın kapsamları içinde olan kapsamlar. Belirtilmezse uygulama yalnızca izin verilen okuma kapsamlarını alır.
`publicOrgId`	Hayır	Müşterinin Flowella web adresindeki altı haneli kuruluş numarası. Belirtilmezse Flowella, kişinin o anda çalıştığı kuruluşu kullanır.

İstek geçersizse Flowella onay ekranı yerine bir hata gösterir ve yönlendirme yapmaz. Bu, örneğin redirect_uri eşleşmediğinde veya bir kapsama izin verilmediğinde olur.

Müşterinin gördükleri

Kişi oturum açmamışsa Flowella önce oturum açmasını ister.
Kişi kuruluşun Owner veya Admin kullanıcısı olmalıdır. Diğer herkes Owner or admin role required to authorize apps hatasını görür.
Authorize app ekranı Client ID: ve Requested scopes: bilgilerinizi gösterir. Uygulamanız bir scope göndermediyse ekranda This app will receive its default allowed scopes. yazar.
Kişi Allow access veya Deny seçeneğini seçer.

Allow access, tarayıcıyı sorgu dizesinde code ve state ile redirect_uri adresinize gönderir. Kod 10 dakika geçerlidir ve bir kez çalışır. Deny, tarayıcıyı error=access_denied, bir error_description ve state değerinizle redirect_uri adresinize gönderir.

Kodu belirteçlerle değiştirin

Sunucunuz kodu belirteç uç noktasında değiştirir. İstemci kimliğiniz ve sırrınızla, HTTP Basic kimlik doğrulamasıyla veya gövdede client_id ve client_secret olarak kimlik doğrulayın. Gövde form kodlu veya JSON olabilir.

curl -X POST "https://app.flowella.io/api/oauth/token" \
  -u "$FLOWELLA_CLIENT_ID:$FLOWELLA_CLIENT_SECRET" \
  -d grant_type=authorization_code \
  -d code="$CODE" \
  -d redirect_uri="https://example.com/oauth/callback" \
  -d code_verifier="$CODE_VERIFIER"

Yanıt belirteçleri içerir:

{
  "access_token": "fla_xxxxxxxxxxxxxxxx",
  "token_type": "bearer",
  "expires_in": 3600,
  "refresh_token": "flr_xxxxxxxxxxxxxxxx",
  "scope": "messages:read contacts:read"
}

Belirteç	Başlangıcı	Geçerlilik süresi
Erişim belirteci	`fla_`	1 saat
Yenileme belirteci	`flr_`	30 gün ve yalnızca bir kez kullanılana kadar

Belirteç uç noktası, her istemci kimliği ve IP adresi için dakikada 30 istek kabul eder. Bunun üzerinde Retry-After başlığıyla 429 döndürür.

API’yi çağırın

Erişim belirtecini tıpkı bir API anahtarı gibi bearer belirteci olarak gönderin:

Authorization: Bearer fla_xxxxxxxxxxxxxxxx

Belirteç yalnızca onu onaylayan kuruluş için ve yalnızca verilen kapsamlar için çalışır. Bu kapsamların dışındaki bir istek 403 INSUFFICIENT_SCOPE döndürür. Her erişim belirtecinin kendi hız sınırı vardır. Bkz. API’ye giriş.

POST /v1/templates/send yalnızca API anahtarlarını kabul eder ve OAuth erişim belirteçlerini 401 ile reddeder.

Bir erişim belirtecini yenileyin

Erişim belirtecinin süresi dolmadan önce grant_type=refresh_token, refresh_token ve istemci kimlik doğrulamanızla yenisini isteyin. Yanıtta yeni bir erişim belirteci ve yeni bir yenileme belirteci bulunur ve eski yenileme belirteci çalışmayı durdurur. Biri daha önce kullanılmış bir yenileme belirteci sunarsa Flowella o yetkilendirmeden verilen tüm belirteçleri iptal eder ve müşterinin uygulamanızı yeniden onaylaması gerekir.

Kendi kuruluşunuza erişin

Uygulamanın sahibi olan kuruluş için API’yi çağırmak üzere istemci kimlik doğrulamanız ve isteğe bağlı bir scope ile grant_type=client_credentials kullanın. Yenileme belirteci olmadan bir erişim belirteci alırsınız. Ardından uygulamanız kendi kuruluşunuzda Installed apps altında görünür.

Bir belirteci iptal edin veya inceleyin

Uç nokta	Ne yapar
`POST https://app.flowella.io/api/oauth/revoke`	Gönderdiğiniz `token` değerini, onunla birlikte verilen tüm belirteçlerle birlikte iptal eder.
`POST https://app.flowella.io/api/oauth/introspect`	`token` değerinin `active` olup olmadığını; `scope`, `client_id`, `organization_id` ve sona erme zamanıyla birlikte döndürür.

Her iki uç nokta da istemci kimlik doğrulamanızı gerektirir. https://app.flowella.io/.well-known/oauth-authorization-server adresindeki keşif belgesi her uç noktayı ve desteklenen seçeneği listeler.

Yüklü uygulamaları inceleyin ve iptal edin

Müşteriler onayladıkları uygulamaları Installed apps altında yönetir. Owner veya Admin rolüne ihtiyacınız vardır. Liste şunları gösterir:

Sütun	Ne gösterir
App	Uygulamanın adı ve altında istemci kimliği.
Scopes	Uygulamaya verilen kapsamlar.
Installed	Uygulamanın ilk ne zaman onaylandığı.
Actions	Revoke veya bir Revoked rozeti.

Bir uygulamayı iptal etmek için:

Settings bölümüne gidin, ardından Developer grubunda Installed apps seçeneğini seçin.
Uygulamanın satırındaki Revoke seçeneğini seçin.
Revoke this install? Existing tokens stop working. istemini onaylayın.

Uygulamanın belirteçleri hemen çalışmayı durdurur ve uygulama bunları yenileyemez. Satır listede bir Revoked rozetiyle kalır. Uygulamaya yeniden erişim vermek için bir Owner veya Admin onu onay ekranında yeniden onaylar.

Kendi kuruluşunuzda kendi uygulamanızı iptal etmek istemci kimlik bilgileri izin türünü durdurmaz: uygulama yeni bir belirteç isteyebilir ve bu da yüklemeyi yeniden açar. Kendi uygulamanızı tamamen kesmek için onu Developer apps altında silin.

Bir uygulamayı silin

Developer apps bölümünde uygulamanın satırındaki Delete seçeneğini seçin ve Delete this app and its tokens? istemini onaylayın. Flowella uygulamayı, onu onaylayan her kuruluştaki yüklemesini ve tüm belirteçlerini kaldırır. Bu işlem geri alınamaz.

Sorun giderme

Could not load developer apps veya Could not load installed apps

Bu ekranları yalnızca Owner ve Admin kullanıcıları görüntüleyebilir. Bir Owner veya Admin’den uygulamayı sizin için yönetmesini isteyin. Roller uygulamada değiştirilemez: bkz. Birinin rolünü değiştirin.

Yönlendirme URI'si uyuşmazlığı

İstekteki redirect_uri, şema, yol ve sondaki eğik çizgi dahil olmak üzere uygulamanın kayıtlı yönlendirme URI’lerinden biriyle tam olarak eşleşmelidir. Kodu değiştirirken aynı değer yeniden gönderilmelidir. Bir uygulamanın yönlendirme URI’lerini düzenleyemezsiniz, bu nedenle farklı bir URI’ye ihtiyacınız varsa yeni bir uygulama kaydedin.

invalid_scope

İstenen bir kapsam yanlış yazılmış veya uygulamanın kapsamlarından biri değil. Yalnızca uygulamayı kaydederken işaretlediğiniz kapsamları isteyin.

Owner or admin role required to authorize apps

Uygulamayı onaylayan kişi kuruluşun Owner veya Admin kullanıcısı değil. Bir Owner veya Admin’den yetkilendirmeyi tamamlamasını isteyin.

Kod değişimi başarısız oluyor

Authorization code expired ve Authorization code already used mesajları yetkilendirmeyi yeniden başlatmanız gerektiği anlamına gelir: kodlar 10 dakika geçerlidir ve bir kez çalışır. PKCE verification failed, code_verifier değerinin gönderdiğiniz code_challenge ile eşleşmediği anlamına gelir.

İlgili

API'ye giriş

Kimlik doğrulama, kapsamlar, hız sınırları ve hatalar.

Developer hub

Son API istekleri, hızlı başlangıçlar ve API sandbox.

API anahtarları

Kendi betikleriniz ve entegrasyonlarınız için daha basit erişim.

Webhook başvurusu

Uygulamanızı yükleyen kuruluşlardaki olaylara tepki verin.

Başlarken

Temel bilgiler

Uygulamayı kullanma

Ayarlar

Meta ve WhatsApp kurulumu

HubSpot entegrasyonu

Flow'lar ve kampanyalar

API referansı

Sorun giderme

Değişiklik günlüğü

OAuth ile bir iş ortağı uygulaması kaydedin ve yüklü uygulamaları yönetin

Nasıl çalışır

Başlamadan önce

Bir uygulama kaydedin

Bir müşteriyi yetkilendirmeden geçirin

Müşterinin gördükleri

Kodu belirteçlerle değiştirin

API’yi çağırın

Bir erişim belirtecini yenileyin

Kendi kuruluşunuza erişin

Bir belirteci iptal edin veya inceleyin

Yüklü uygulamaları inceleyin ve iptal edin

Bir uygulamayı silin

Sorun giderme

İlgili

API'ye giriş

Developer hub

API anahtarları

Webhook başvurusu

​Nasıl çalışır

​Başlamadan önce

​Bir uygulama kaydedin

​Bir müşteriyi yetkilendirmeden geçirin

​Müşterinin gördükleri

​Kodu belirteçlerle değiştirin

​API’yi çağırın

​Bir erişim belirtecini yenileyin

​Kendi kuruluşunuza erişin

​Bir belirteci iptal edin veya inceleyin

​Yüklü uygulamaları inceleyin ve iptal edin

​Bir uygulamayı silin

​Sorun giderme

​İlgili

API'ye giriş

Developer hub

API anahtarları

Webhook başvurusu

Nasıl çalışır

Başlamadan önce

Bir uygulama kaydedin

Bir müşteriyi yetkilendirmeden geçirin

Müşterinin gördükleri

Kodu belirteçlerle değiştirin

API’yi çağırın

Bir erişim belirtecini yenileyin

Kendi kuruluşunuza erişin

Bir belirteci iptal edin veya inceleyin

Yüklü uygulamaları inceleyin ve iptal edin

Bir uygulamayı silin

Sorun giderme

İlgili