Geliştiriciler, tekerleği yeniden icat etmeden sağlam kurumsal özellikler uygulama zorluğuyla karşı karşıya. WorkOS API, kimlik doğrulama, kullanıcı sağlama ve uygulamanızla birlikte ölçeklenen uyumluluk araçları için birleşik bir arayüz sunarak güçlü bir çözüm olarak ortaya çıkıyor. İster tek oturum açma (SSO) akışlarını yönetin, ister dizin verilerini senkronize edin, bu API karmaşık entegrasyonları basitleştirir.
button
WorkOS API Nedir? Temel Bileşenleri ve Kurumsal Değeri
WorkOS API, uygulamalarına kurumsal düzeyde özellikler yerleştirmesi gereken geliştiriciler için özel olarak tasarlanmış bir RESTful arayüzüdür. GitHub ve Vercel gibi şirketlerdeki mühendisler, farklı üçüncü taraf hizmetlerini yönetmek zorunda kalmadan kimlik doğrulama, kullanıcı yaşam döngüsü yönetimi ve güvenlik uyumluluğunu ele almak için ona güveniyorlar. Temelinde, API, SAML, OAuth 2.0 ve SCIM gibi protokollerden gelen karmaşıklıkları soyutlayarak ekiplerin temel ürün mantığına odaklanmasını sağlıyor.
Desteklediği birincil ürünleri düşünün. AuthKit, geliştiricilerin parola tabanlı oturum açma, sihirli bağlantılar veya çok faktörlü kimlik doğrulama (MFA) aracılığıyla kullanıcıları oluşturduğu, kimlik doğruladığı ve yönettiği eksiksiz bir kullanıcı yönetimi paketi sunar. Örneğin, /user_management/users uç noktasına basit bir POST isteğiyle bir kullanıcı kaydı başlatırsınız ve WorkOS karşılığında e-posta doğrulamayı ve oturum belirteçlerini yönetir. Bu, özel arka uç mantığına olan ihtiyacı ortadan kaldırır ve kullanıcı referanslarına göre geliştirme süresini %50'ye kadar azaltır.
Ayrıca, Tek Oturum Açma (SSO) entegrasyonu, /sso/authorize gibi özel uç noktalar aracılığıyla parlar. Geliştiriciler, kullanıcıları Okta veya Microsoft Entra ID gibi kimlik sağlayıcılarına yönlendiren yetkilendirme URL'leri oluşturur. Kimlik doğrulandıktan sonra, API talepleri içeren bir profil nesnesi döndürerek sorunsuz erişim kontrolü sağlar. Veri senkronizasyonuna geçiş yapıldığında, Directory Sync, SCIM uyumlu API'ler aracılığıyla Google Workspace gibi kaynaklardan kullanıcıları ve grupları sağlar. /directory_users adresine GET isteğiyle dizin kullanıcılarını listelersiniz ve WorkOS, yoklama yapmadan uygulamanızın senkronize kalmasını sağlayan webhook'lar aracılığıyla gerçek zamanlı güncellemeler için olaylar yayar.
Kuruluşlar başka bir temel taşı oluşturur. API, /organizations ve /organization_memberships aracılığıyla rolleri ve üyelikleri atayarak çoklu kiracılı yapıları modellemenizi sağlar. Denetim Kayıtları, kullanıcı oluşturmalardan SSO iddialarına kadar her eylemi yakalar ve SOC 2 gibi uyumluluk denetimleri için CSV veya SIEM araçlarına dışa aktarılır. Events API, zaman damgaları veya kimliklerle filtrelenmiş user.created veya dsync.group.updated gibi değişiklikleri yayınlayarak bunu daha da geliştirir.
WorkOS API'sini farklı kılan nedir? Güvenlik ve ölçeklenebilirliği önceliklendirir. Tüm istekler HTTPS'yi zorunlu kılar ve AuthKit için 10 saniyede 500 yazmadan dakikada 6.000 genel isteğe kadar değişen oran sınırlamaları, performansı korurken kötüye kullanımı önler. Vault, hassas veriler için bağlama duyarlı anahtarlar kullanarak şifrelenmiş depolama ekleyerek ihlalleri azaltır. Radar ise, dolandırıcılık için oturum açma girişimlerini analiz eder ve anormal davranışı proaktif olarak engellemek için risk skorları döndürür.
Uygulamada, bu bileşenler gerçek dünya ihtiyaçlarını karşılar. Kurumsal müşterileri işe alan bir SaaS platformu, kimlikleri birleştirmek için SSO'yu, erişim sağlamak için Directory Sync'i ve uyumluluğu göstermek için Denetim Kayıtlarını kullanır. Geliştiriciler tutarlılığı takdir eder: her uç nokta, JSON yükleri ve standart HTTP durum kodları ile REST kurallarına uyar. Geçersiz anahtarlar için 401 gibi hatalar, hızlı hata ayıklama için açıklayıcı mesajlar içerir.
Ayrıca, API geliştirici geri bildirimleriyle birlikte gelişir. 2025'teki son güncellemeler, üçüncü taraf OAuth entegrasyonları için geliştirilmiş Pipes ve kademeli yayılımlar için geliştirilmiş Feature Flags'ı tanıttı. Bu eklemeler, WorkOS API'sinin GDPR gibi değişen düzenlemeler ve sıfır güven mimarilerindeki ortaya çıkan tehditler arasında güncel kalmasını sağlıyor.
Değerini ölçmek için entegrasyon hızını düşünün. Ekipler, önceden oluşturulmuş SDK'lar ve pano araçları sayesinde SSO'yu haftalar yerine saatler içinde dağıttıklarını bildiriyor. Ancak başarı, bir sonraki bölümde ele aldığımız erişim protokollerini anlamaya bağlıdır.
WorkOS API'ye Erişme: Kimlik Doğrulama, SDK'lar ve Uç Nokta Temelleri
Geliştiriciler WorkOS API'ye güvenlik ve kolaylığı vurgulayan basit bir süreçle erişir. Bir WorkOS hesabı oluşturarak başlayın. Oturum açtıktan sonra, Panonun API Anahtarları bölümüne gidin.
sk_ ile başlayan gizli bir anahtar oluşturun; bu, tüm istekleriniz için Taşıyıcı belirteciniz olarak hizmet eder. Üretim anahtarları yalnızca bir kez görüntülenir, bu nedenle bunları ortam değişkenlerinde veya AWS Secrets Manager gibi gizli yöneticilerde güvenli bir şekilde saklayın.
Kimlik doğrulama, anahtarı Authorization başlığına dahil etmeyi gerektirir: Bearer sk_example_123456789. Temel URL https://api.workos.com'dur ve tüm trafik yükleri şifrelemek için HTTPS üzerinden gerçekleştirilir. Hazırlık ortamları, canlı verileri etkilemeden güvenli denemelere izin veren test için ayrı anahtarlar kullanır. Bir istek izinleri eksikse, 403 Forbidden yanıtı beklenebilir; geçersiz anahtarlar 401 Unauthorized hatasını tetikler.
WorkOS, popüler diller için yerel SDK'lar sağlayarak çağrıları kolaylaştırır. Node.js için npm aracılığıyla yükleyin: npm install @workos-inc/node. const workos = new WorkOS('sk_example_123456789'); ile başlatın. Python kullanıcıları pip install workos çalıştırır, ardından from workos import Client; client = Client(api_key='sk_example_123456789'). Ruby, Go, Java, .NET ve Elixir için benzer sarmalayıcılar mevcuttur ve her biri serileştirmeyi, yeniden denemeleri ve değişmezlik anahtarlarını otomatik olarak yönetir.
Uç noktalar kaynağa göre düzenlenir. Kuruluşlar için, /organizations adresine POST isteği yeni bir varlık oluşturur:
{
"name": "Acme Corp",
"domains": ["acme.com"]
}
Yanıt, /organization_memberships aracılığıyla üye ekleme gibi sonraki işlemler için bir id içerir. /user_management altındaki AuthKit uç noktaları, kullanıcılar üzerinde CRUD işlemlerini destekler. Bir kullanıcıyı şununla oluşturun:
{
"email": "user@acme.com",
"password": "securepass123"
}
Oturumlar, /user_management/sessions aracılığıyla oluşturulur ve ön uç depolama için bir belirteç döndürür. SSO akışları /sso/authorize?client_id=client_123&redirect_uri=https://yourapp.com/callback&state=xyz ile başlar. Sağlayıcı yönlendirmesinden sonra, bir profil için kodu /sso/token adresinde değiştirin.
Directory Sync, Panoda bir dizin yapılandırmayı ve Google API anahtarları gibi sağlayıcı kimlik bilgilerini sağlamayı gerektirir. Ardından, senkronize verileri almak için /directories/{id}/users adresini sorgulayın. Olaylar, /events?event_types[]=user.created&after=2025-01-01T00:00:00Z aracılığıyla alınır, limit ve after imleçleriyle sayfalandırılır.
Oran sınırlamaları IP veya anahtar başına uygulanır, bu nedenle 429 yanıtları için üstel geri çekilme uygulayın. Pano, kotaları izlemek için kullanım analitiği sunar. Test için, belgelerden sağlanan Postman koleksiyonunu veya cURL örneklerini kullanın. İstekleri görselleştirmek, otomatik belge oluşturmak ve yanıtları simüle etmek için bunları Apidog'a aktarın; bu, doğrulama sırasında saatler kazandırır.
Önkoşullar, /organization_domains/verify için DNS TXT kayıtları aracılığıyla kuruluş alan adlarını doğrulamayı içerir. Yönlendirme URL'leri, Panoda yapılandırıldığı gibi tam olarak eşleşmelidir. Ayarlandığında, uygulamanız MFA zorlukları veya e-posta doğrulamaları gibi uç durumları özel akışlar aracılığıyla yönetir.
Bu erişim modeli, geliştiricilerin kontrolü korurken hızlı bir şekilde entegre olmasını sağlar. Temeller yerleştirildikten sonra, fiyatlandırma kararları mantıksal olarak takip eder.
WorkOS API Fiyatlandırması: Girişimlerden Kurumsal Firmalara Esnek Modeller
WorkOS, fiyatlandırmayı aktif kullanıcılar ve bağlantılar etrafında yapılandırarak büyüyen ekipler için erişilebilirliği teşvik eder. Kullandıkça öde modeli, aylık ilk 1 milyon aktif kullanıcı için hiçbir ücret talep etmez; bu, takvim ayında kaydolan, oturum açan veya profil güncelleyen kullanıcılar olarak tanımlanır. Bunun ötesinde, maliyetler kullanıma göre ölçeklenir ve verimliliği ödüllendirmek için otomatik hacim indirimleri uygulanır.
Bağlantılar, SSO veya Directory Sync aracılığıyla son kullanıcılara yönelik bağlantıları temsil eder ve sağlayıcıdan (örn. Okta veya Azure AD) veya senkronize edilen toplam kullanıcı sayısından bağımsız olarak sabit ücretlere tabidir. Bu tekdüzelik tahmin yapmayı basitleştirir. Geliştiriciler, CI/CD işlem hatları için ideal olan hazırlık ortamında sınırsız test bağlantısını ücretsiz olarak sağlayabilir.
Kararlı büyüme için, yıllık kredi planı, %99,99 çalışma süresi SLA'ları, rehberli başlangıç oturumları ve öncelikli destek gibi avantajlarla birlikte ön ödemeli krediler sunar. Ekipler indirimli krediler için ön ödeme yaparak 12 ay boyunca oranları sabitler. Aylık 99 ABD doları tutarındaki özel alan adı seçeneği, AuthKit sayfalarını, Yönetici Portallarını ve e-postalarını alan adınızla markalayarak kullanıcı güvenini artırır.
Kurumsal planlar, özel Slack kanalları, üç aylık mimari incelemeler ve 7/24 yanıt SLA'ları dahil olmak üzere daha da özelleştirilir. Tüm katmanlar e-posta desteği, API durum uyarıları ve kapsamlı belgeler sağlar. Sizi bağlayan uzun vadeli taahhütler yoktur; ihtiyaçlar geliştikçe büyüyebilir veya küçülebilirsiniz.
WorkOS API Entegrasyonu: Adım Adım Örnekler ve En İyi Uygulamalar
Entegrasyon, SDK seçimiyle başlar ancak yürütme yapılandırılmış yaklaşımlar gerektirir. Bir ağ geçidi özelliği olarak SSO ile başlayın. Node.js'de bir profil alın:
const profile = await workos.sso.getProfileAndToken({
code: req.query.code,
clientID: process.env.CLIENT_ID
});
Belirteci güvenli bir şekilde saklayın, ardından taleplere göre rotaları yetkilendirin. Dizin Senkronizasyonu için, olayları almak üzere webhook'lar ayarlayın. Uç noktanıza POST isteğiyle şunları gönderin:
{
"event": "dsync.user.created",
"data": { "id": "user_123", "email": "user@acme.com" }
}
Veritabanınıza ayrıştırın ve upsert edin, nihai tutarlılığı sağlayın. AuthKit kullanıcı akışlarında parlar. MFA'yı /auth/factors/enroll ile kaydedin, TOTP kodlarını /auth/challenges/verify adresinde doğrulayın. Sihirli Kimlik Doğrulama, kodları /magic_auth/send_code aracılığıyla gönderir ve /magic_auth/verify_code adresinde onaylar.
Kuruluşları çoklu kiracılı tarzda yönetin. Kullanıcıları /invitations aracılığıyla davet edin, durumu /organization_memberships içinde takip edin. Denetim Kayıtları, uyumluluk raporları için filtreleme yaparak /audit_logs/events aracılığıyla entegre olur.
En iyi uygulamalar arasında yeniden denemeler için değişmezlik (başlıklarda benzersiz anahtarlar kullanın) bulunur. Kontrol Paneli analitikleri aracılığıyla izleyin, oran sınırı isabetlerinde uyarı verin. Vault için, depolamadan önce PII'yi şifreleyin: /vault/v1/kv adresine şifreli metin ile POST isteği gönderin.
Apidog bu iş akışını geliştirir. WorkOS şemalarını içe aktarın, hazırlık ortamına karşı koleksiyonları çalıştırın ve API spesifikasyonları üzerinde işbirliği yapın. Sağlayıcı erişimindeki boşlukları kapatarak çevrimdışı test için Dizin Senkronizasyonu yüklerini taklit eder.
Yaygın hatalar? Yanlış eşleşen yönlendirme URL'leri sessiz başarısızlıklara neden olur; erken doğrulayın. Alan adı doğrulamasını gözden kaçırmak SSO iddialarını engeller. Çoklu organizasyonluysa, istekleri anahtarlar arasında parçalayarak ölçeklendirin.
2025'te, uç kimlik doğrulama için WorkOS'u Vercel gibi sunucusuz mimarilerle eşleştirin. Bu kombinasyon, WorkOS'un düşük gecikmeli uç noktalarından yararlanarak küresel olarak dağıtılır.
Gelişmiş WorkOS API Kullanım Durumları: Dolandırıcılık Tespitinden Özellik Yönetimine
Temel özelliklerin ötesinde, API sofistike senaryoların önünü açar. Radar, oturum açma risklerini değerlendirir: /radar/attempts adresine POST girişimleri gönderir, "izin ver" veya "engelle" gibi kararlar alır. Güvenilir IP'leri beyaz listeye almak için /radar/lists aracılığıyla beyaz listelerle entegre edin.
Feature Flags, /feature_flags/{slug}/targets aracılığıyla her kullanıcı veya organizasyon için değerlendirilerek açılıp kapatılır. Pipes, GitHub'a OAuth'ı yönetir: /data_integrations/github/token adresinde belirteçler oluşturur.
/portal/generate_link adresinden gelen Yönetici Portalı bağlantıları, self servis yapılandırmalarını yerleştirir. Olay senkronizasyonu, 30 gün öncesine kadar sorgulama yaparak uygulamaları güncel tutar.
Bu durumlar genişletilebilirliği gösterir. Bir fintech uygulaması, anormallik tespiti ve raporlama için Radar ve Denetim Kayıtlarını kullanır. E-ticaret platformları, kuruluş boyutuna göre özellikler işaretler.
Sonuç
WorkOS API, geliştiricilere kurumsal özellikleri verimli bir şekilde sunma gücü verir. Temel erişimden gelişmiş entegrasyonlara kadar iş akışlarını kolaylaştırırken maliyetleri de kontrol altında tutar. Bu uç noktaları uygulamalı olarak test etmek için Apidog'u ücretsiz indirin; API etkileşimlerinizi bugün dönüştürün.
Bu stratejileri uygulayın ve uygulamanızın güvenli bir şekilde ölçeklendiğini görün. Teknoloji yığınınızı geleceğe hazırlayın; API'nin yol haritası sürekli yenilik vaat ediyor.
button