Kimlik doğrulama

API anahtarları (entegrasyonlar için önerilir)

API anahtarı, hesabınızdaki bir üyeye bağlı kişisel bir erişim token’ıdır.

• Ayarlar → Eklentiler → RolChat API anahtarları bölümünde bir tane oluşturun. Gizli değer bir kez gösterilir; sonrasında yalnızca ilk on karakteri görünür ve RolChat yalnızca bir SHA-256 hash’i saklar.
• Biçim: rcp_ ve ardından base64url biçiminde 32 rastgele bayt, toplamda yaklaşık 45 karakter. Önek, bir anahtarı loglarda tanınabilir ve bir oturum token’ından ayırt edilebilir kılar.
• Kapsamlar: anahtar oluşturulurken sabit bir yetenek kataloğundan seçilir. Bir anahtar asla onu oluşturan üyeden fazlasını yapamaz: her çağrıda iki koşul da kontrol edilir; yetenek anahtarın kapsamlarındadır ve üye buna hâlâ sahiptir. Üyenin rolünü daraltırsanız anahtar da onunla birlikte daralır.
• Geçerlilik süresi: anahtarların süresi kendiliğinden dolmaz. Bir anahtarı profil sayfasından veya DELETE /api/v1/tokens/:id ile iptal edin; iptal hemen geçerli olur. Yerinde döndürme yoktur: iptal edin ve yeni bir anahtar oluşturun.
• Oluşturma ve iptal işlemleri denetim kaydına yazılır.

Anahtarı bir bearer token olarak gönderin - ayrı bir API anahtarı başlığı yoktur:

curl https://api.rolchat.com/api/v1/contacts?limit=20 \
  -H "Authorization: Bearer rcp_…" \
  -H "X-Account-Id: 7c1d2c6e-…"

Eklenti API anahtarıyla yapılan istekler dakikada 300 ile sınırlıdır.

JWT oturumları

Web uygulaması ve mobil SDK’lar e-posta ve şifreyle (veya Google ya da Apple ile) oturum açar ve bir token çifti alır.

Token	Geçerlilik süresi	Notlar
Access token	15 dakika	RS256, /.well-known/jwks.json adresindeki JWKS’e karşı doğrulanır
Refresh token	30 gün	Her yenilemede döndürülür; döndürülmüş bir token’ın yeniden kullanılması tüm zinciri iptal eder

Claim’ler: sub (kullanıcı), acc (hesap), rl (rol) ve site bazlı roller için sts (izin verilen siteler).

POST /auth/login, /auth/refresh, /auth/swap-company ve /auth/logout, bir sonraki bölümde açıklanan X-Account-Id başlığını taşımaması gereken yegâne kimlik doğrulama akışı endpoint’leridir.

X-Account-Id başlığı

Yukarıdaki dördü dışındaki her kimliği doğrulanmış istek, üzerinde işlem yaptığı hesabı taşımalıdır:

X-Account-Id: <account uuid>

Sunucu, başlığın token’ın acc claim’ine (veya API anahtarının hesabına) eşit olduğunu kontrol eder. Eksik başlık 400 missing_required_header, uyuşmazlık ise 403 account_context_mismatch döndürür. Başlık, bir istemci hatasının veya yeniden oynatılan bir token’ın başka bir kiracının verilerini asla sessizce okuyamaması için vardır: uyuşmazlık herhangi bir sorgu çalışmadan reddedilir ve her log satırı token çözülmeden bir hesaba atfedilebilir.

Çok şirketli kullanıcılar

Bir kişi birden fazla şirkete ait olabilir. Her şirketin kendi token’ı (kendi acc claim’i) vardır. Geçiş yapmak için:

POST /api/v1/auth/swap-company
Authorization: Bearer <current access token>

{ "account_id": "<target uuid>" }

Hedef, çağıranın available_companies listesinden biri olmalıdır (oturum açılırken döndürülür), aksi halde 403 forbidden. Yanıt, hedefe göre kapsamlandırılmış yeni bir access ve refresh token çiftidir; eski refresh token iptal edilir ve bir auth.account.swapped denetim olayı yazılır.

Çok faktörlü kimlik doğrulama

TOTP tabanlı MFA üye başına etkinleştirilebilir ve hesap başına zorunlu kılınabilir. Açık olduğunda POST /auth/login bir doğrulama isteği döndürür ve oturum POST /auth/mfa/verify ile tamamlanır. Yedek kodlar etkinleştirme sırasında verilir.

Oturum açma koruması

• Oturum açma yolları IP başına dakikada 10 deneme ve e-posta başına 15 dakikada 5 deneme ile sınırlıdır.
• On başarısız oturum açma denemesi e-postayı 30 dakika kilitler; yanıt code: account_locked taşır.
• reCAPTCHA eylem başına (kayıt, oturum açma, şifre sıfırlama) etkinleştirilebilir; herkese açık başlangıç yapılandırması GET /api/v1/captcha üzerinden sunulur.