OAuth

Twenty, kullanıcıya dönük uygulamalar için yetkilendirme kodu + PKCE’yi ve sunucudan sunucuya erişim için istemci kimlik bilgilerini kullanarak OAuth 2.0’ı uygular. İstemciler RFC 7591 aracılığıyla dinamik olarak kaydedilir — bir kontrol panelinde manuel kurulum gerekmez.

OAuth Ne Zaman Kullanılır

Senaryo	Kimlik Doğrulama Yöntemi
Dahili betikler, otomasyon	API Anahtarı
Bir kullanıcının adına hareket eden harici uygulama	OAuth — Yetkilendirme Kodu
Sunucudan sunucuya, kullanıcı bağlamı yok	OAuth — İstemci Kimlik Bilgileri
UI uzantılarına sahip Twenty Uygulaması	Uygulamalar (OAuth otomatik olarak yönetilir)

Bir İstemci Kaydedin

Twenty, RFC 7591 uyarınca dinamik istemci kaydını destekler. Manuel kurulum gerekmez — programatik olarak kaydedin:

POST /oauth/register
Content-Type: application/json

{
  "client_name": "My Integration",
  "redirect_uris": ["https://myapp.com/callback"],
  "grant_types": ["authorization_code"],
  "token_endpoint_auth_method": "client_secret_post"
}

Yanıt:

{
  "client_id": "abc123",
  "client_secret": "secret456",
  "client_name": "My Integration",
  "redirect_uris": ["https://myapp.com/callback"]
}

client_secret değerini güvenli bir şekilde saklayın — daha sonra geri alınamaz.

Kapsamlar

Kapsam	Erişim
`api`	Core ve Metadata API’lerine tam okuma/yazma erişimi
`profile`	Kimliği doğrulanmış kullanıcının profil bilgilerini okuyun

Kapsamları boşlukla ayrılmış bir dize olarak isteyin: scope=api profile

Yetkilendirme Kodu Akışı

Uygulamanız bir Twenty kullanıcısı adına hareket ettiğinde bu akışı kullanın.

1. Kullanıcıyı yetkilendirmek için yönlendirin

GET /oauth/authorize?
  client_id=YOUR_CLIENT_ID&
  response_type=code&
  redirect_uri=https://myapp.com/callback&
  scope=api&
  state=random_state_value&
  code_challenge=CHALLENGE&
  code_challenge_method=S256

Parametre	Zorunlu	Açıklama
`client_id`	Evet	Kayıtlı istemci kimliğiniz
`response_type`	Evet	`code` olmalıdır
`redirect_uri`	Evet	Kayıtlı bir yönlendirme URI’siyle eşleşmelidir
`scope`	Hayır	Boşlukla ayrılmış kapsamlar (varsayılan: `api`)
`state`	Önerilen	CSRF saldırılarını önlemek için rastgele bir dize
`code_challenge`	Önerilen	PKCE challenge (doğrulayıcının SHA-256 karması, base64url ile kodlanmış)
`code_challenge_method`	Önerilen	PKCE kullanılırken `S256` olmalıdır

Kullanıcı bir onay ekranı görür ve erişimi onaylar veya reddeder.

2. Geri dönüşü işleyin

Yetkilendirmeden sonra, Twenty redirect_uri adresinize geri yönlendirir:

https://myapp.com/callback?code=AUTH_CODE&state=random_state_value

state değerinin gönderdiğinizle eşleştiğini doğrulayın.

3. Kodu belirteçlerle değiş tokuş edin

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
code=AUTH_CODE&
redirect_uri=https://myapp.com/callback&
client_id=YOUR_CLIENT_ID&
client_secret=YOUR_CLIENT_SECRET&
code_verifier=YOUR_PKCE_VERIFIER

Yanıt:

{
  "access_token": "eyJhbG...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "dGhpcyBpcyBh..."
}

4. Erişim belirtecini kullanın

GET /rest/companies
Authorization: Bearer ACCESS_TOKEN

5. Süresi dolduğunda yenileyin

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&
refresh_token=YOUR_REFRESH_TOKEN&
client_id=YOUR_CLIENT_ID&
client_secret=YOUR_CLIENT_SECRET

İstemci Kimlik Bilgileri Akışı

Sunucudan sunucuya, kullanıcı etkileşimi olmayan entegrasyonlar için:

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&
client_id=YOUR_CLIENT_ID&
client_secret=YOUR_CLIENT_SECRET&
scope=api

Döndürülen belirteç, belirli bir kullanıcıya bağlı olmayan, çalışma alanı düzeyinde erişime sahiptir.

Sunucu Keşfi

Twenty, OAuth yapılandırmasını standart bir keşif uç noktasında yayımlar:

GET /.well-known/oauth-authorization-server

Bu, tüm uç noktaları, desteklenen grant türlerini, kapsamları ve yetenekleri döndürür — genel OAuth istemcileri oluşturmak için kullanışlıdır.

API Uç Noktaları Özeti

Uç nokta	Amaç
`/.well-known/oauth-authorization-server`	Sunucu üstverisi keşfi
`/oauth/register`	Dinamik istemci kaydı
`/oauth/authorize`	Kullanıcı yetkilendirmesi
`/oauth/token`	Belirteç değişimi ve yenileme

Ortam	Temel URL
Bulut	`https://api.twenty.com`
Kendi Kendine Barındırma	`https://{your-domain}`

OAuth ve API Anahtarları

	API Anahtarları	OAuth
Kurulum	Ayarlar’da oluşturun	Bir istemci kaydedin, akışı uygulayın
Kullanıcı bağlamı	Yok (çalışma alanı düzeyi)	Belirli bir kullanıcının izinleri
En uygun	Betikler, dahili araçlar	Harici uygulamalar, çok kullanıcılı entegrasyonlar
Belirteç döndürme	Manuel	Yenileme belirteçleri aracılığıyla otomatik olarak
Kapsama dayalı erişim	Tam API erişimi	Kapsamlar aracılığıyla ayrıntılı

Genel Bakış

Uygulamalar

API

Kendi Kendine Barındırma

Katkıda Bulunun

OAuth Ne Zaman Kullanılır

Bir İstemci Kaydedin

Kapsamlar

Yetkilendirme Kodu Akışı

1. Kullanıcıyı yetkilendirmek için yönlendirin

2. Geri dönüşü işleyin

3. Kodu belirteçlerle değiş tokuş edin

4. Erişim belirtecini kullanın

5. Süresi dolduğunda yenileyin

İstemci Kimlik Bilgileri Akışı

Sunucu Keşfi

API Uç Noktaları Özeti

OAuth ve API Anahtarları

​OAuth Ne Zaman Kullanılır

​Bir İstemci Kaydedin

​Kapsamlar

​Yetkilendirme Kodu Akışı

​1. Kullanıcıyı yetkilendirmek için yönlendirin

​2. Geri dönüşü işleyin

​3. Kodu belirteçlerle değiş tokuş edin

​4. Erişim belirtecini kullanın

​5. Süresi dolduğunda yenileyin

​İstemci Kimlik Bilgileri Akışı

​Sunucu Keşfi

​API Uç Noktaları Özeti

​OAuth ve API Anahtarları

OAuth Ne Zaman Kullanılır

Bir İstemci Kaydedin

Kapsamlar

Yetkilendirme Kodu Akışı

1. Kullanıcıyı yetkilendirmek için yönlendirin

2. Geri dönüşü işleyin

3. Kodu belirteçlerle değiş tokuş edin

4. Erişim belirtecini kullanın

5. Süresi dolduğunda yenileyin

İstemci Kimlik Bilgileri Akışı

Sunucu Keşfi

API Uç Noktaları Özeti

OAuth ve API Anahtarları