Kimlik doğrulama¶

Authorization başlığında tek bir kimlik bilgisi gönderin. Her işlem hangi kimlik bilgisi türlerini kabul ettiğini belirtir.

Hatalar standart hata yanıtını kullanır. Kimlik doğrulama HTTP API ve OAuth2 HTTP API sayfaları kimlik bilgilerinin nasıl verildiğini ve iptal edildiğini belgeler.

Kimlik bilgisi yönetimi¶

Bir kimlik bilgisini elinde tutan herkes onun sahibi gibi davranabilir. Kimlik bilgilerini günlüklerden, analitikten, çökme raporlarından ve kaynak koddan uzak tutun ve yalnızca ihtiyaç duyduğunuz sürece saklayın. Her zaman TLS kullanın.

Bir Authorization kimlik bilgisini asla URL'ye koymayın. Webhook URL'lerinde ve yükleme URL'lerinde URL'nin tamamını gizli bir değer olarak ele alın: yönlendirmeler, günlükler veya referrer bilgisi üzerinden açığa çıkarmayın.

Authorization başlığı¶

Aşağıdaki biçimlerden birini kullanın. Şema öneki büyük/küçük harfe duyarlıdır ve ardından tam olarak bir boşluk gelmelidir.

Yetkilendirme şemaları¶

Kullanıcı oturum token'ı ile OAuth2 erişim token'ı aynı Bearer şemasını kullanır. TEBHOS ikisini token'ın biçiminden ayırt eder. Erişim token'larına açık olarak listelenmemiş bir işleme geçerli bir OAuth2 erişim token'ı göndermek 403 ACCESS_DENIED döndürür.

# User session
curl https://tebhos.com/api/v1/users/@me \
  -H "Authorization: Bearer $TEBHOS_SESSION_TOKEN"

# Bot
curl https://tebhos.com/api/v1/users/@me \
  -H "Authorization: Bot $TEBHOS_BOT_TOKEN"

Token biçimleri¶

Her token'ı opak bir dize olarak ele alın ve değiştirmeden gönderin.

Kullanıcı oturum token'ları¶

Kullanıcı oturum token'ı, sıradan bir kullanıcı hesabının kimliğini doğrular. Giriş ve kayıt işlemleri bu token'ı verir. Bir oturum iptal edilene kadar sürer: çıkış yaparak, oturumu oturum listesinden sonlandırarak, parolayı sıfırlayarak ya da tüm oturumları sonlandırarak. İptal edilmiş bir oturum token'ı hemen 401 UNAUTHORIZED ile reddedilir.

Gateway, oturum token'ını Identify komutunda kabul eder.

Bot token'ları¶

Bot token'ı, bir uygulamanın bot hesabının kimliğini doğrular. Bot hesabının kullanıcı kimliği uygulama kimliğidir. TEBHOS token'ı, noktadan önce adı geçen uygulamayı arayıp noktadan sonraki gizli değeri denetleyerek doğrular.

Bir bot, bot token'larını kabul eden her işlemi kullanabilir; bu da yaygın bot iş yükünü kapsar: mesaj okuma ve gönderme, tepkiler, kanallar, üyeler, roller ve benzeri sunucu kaynakları. Sıradan kullanıcı hesaplarına ayrılmış bir işlem yalnızca kullanıcı oturum token'ını kabul eder ve geçerli bir bot token'ını 403 ACCESS_DENIED ile (geçersiz olanı 401 UNAUTHORIZED ile) yanıtlar. Bot rehberi eksiksiz bir botu adım adım anlatır.

İki işlem yalnızca botlara açıktır:

• GET /gateway/bot bir bot için Gateway URL'sini döndürür ve geçerli bir bot token'ı dışındaki her kimlik bilgisini 401 UNAUTHORIZED ile yanıtlar. Bkz. Gateway HTTP API.
• GET /applications/@me bot token'ının sahibi olan uygulamayı döndürür. Bkz. Uygulamalar.

HTTP'de bot token'ı Bot önekini taşımak zorundadır. Önek yoksa değer kullanıcı oturum token'ı olarak okunur ve istek 401 UNAUTHORIZED ile başarısız olur.

Gateway, bot token'ını Identify içinde yalın hâliyle ya da aynı Bot önekiyle kabul eder.

OAuth2 erişim token'ları¶

OAuth2 erişim token'ı, OAuth2 HTTP API içindeki yetkilendirme kodu akışıyla bir uygulamaya verilir. Authorization: Bearer <token> olarak gönderilir ve kendisine verilen kapsamlarla sınırlıdır.

TEBHOS erişim token'ını OAuth2 kaynak işlemlerinde ve küçük bir okuma işlemleri kümesinde, her biri için gerekli bir kapsamla kabul eder:

Bu işlemlerde token, verildiği kullanıcı olarak davranır; üyelik ve izin denetimleri bir oturumdakiyle aynıdır.

{
  "code": "MISSING_OAUTH_SCOPE",
  "message": "Missing required OAuth2 scope: guilds",
  "required_scope": "guilds"
}

GET /oauth2/userinfo da identify kapsamı olmayan bir token'ı 403 MISSING_OAUTH_SCOPE ile yanıtlar, ancak required_scope alanı olmadan.

Yetkilendirme sonuçları¶

401 yanıtında WWW-Authenticate başlığı yoktur; bu yüzden istemciler gövdedeki code değerini okumalıdır. message insanlar için okunabilir bir metindir ve yerelleştirilmiş olabilir; ayrıştırmayın.

Bir kimlik bilgisi, kimlik bilgisi gerektirmeyen bir işlemin davranışını da değiştirebilir: IP tabanlı kovalar yerine çağıranın kendi hız sınırı kovalarını seçer.

Başarısız kimlik doğrulama¶

Kimlik doğrulama hataları, bir kimlik bilgisinin bilinmeyen, süresi dolmuş, iptal edilmiş veya hatalı biçimli olup olmadığını söylemez. Reddedilen bir kimlik bilgisiyle yeniden denemeyi bırakın ve yenisini edinin. Tekrarlanan başarısız girişler, Hız sınırları sayfasında anlatılan giriş hız sınırlarıyla yavaşlatılır.

Yeni bir konumdan yapılan giriş e-posta onayı için bekletilebilir. Bu durumda POST /auth/login, IP_AUTHORIZATION_REQUIRED kodu ve bir ticket ile 403 döndürür; bkz. Kimlik doğrulama HTTP API.

Sudo modu¶

Parola değiştirme, hesabı silme, bot token'ını sıfırlama veya çok adımlı doğrulamayı (MFA) yönetme gibi bazı hassas hesap işlemleri, hesap sahibinin yeniden doğrulama yapmasını gerektirir. Böyle bir işlem, kanıt yoksa 403 SUDO_MODE_REQUIRED döndürür.

TEBHOS iki kanıt biçimini kabul eder:

• Hassas işlemin istek gövdesinde satır içi kanıt: çok adımlı doğrulaması olan bir hesap için mfa_code (bir TOTP veya yedek kod), bir geçiş anahtarı (passkey) onayından elde edilen sudo_proof ya da çok adımlı doğrulaması olmayan bir hesap için password.
• POST /auth/sudo ile oluşturulan bir sudo izni. İzin beş dakika sürer ve onu oluşturan oturuma bağlıdır; bu yüzden başka bir oturumla yapılan istekleri yükseltmez.

Çok adımlı doğrulama kabul edilen yöntemleri belgeler. Sudo modu yalnızca kullanıcı oturum token'ları için geçerlidir; bunu gerektiren işlemler botlara açık değildir.

Gateway kimlik doğrulaması¶

Bot token'ını veya kullanıcı oturum token'ını bir Authorization başlığında değil, Identify komutunda gönderin. Geçersiz veya iptal edilmiş bir kimlik bilgisi bağlantıyı 4004 kapanış koduyla (kimlik doğrulama başarısız) kapatır. Bkz. İşlem kodları ve kapanış kodları.

Diğer kimlik bilgisi yüzeyleri¶

Bir webhook yürütme işlemi, webhook kimliğini ve token'ını yolunda taşır ve Authorization başlığına ihtiyaç duymaz. Bu sözleşmeyi Webhook'lar tanımlar.

Avatarlar, simgeler ve ekler gibi herkese açık medya yolları kendi yollarıyla adreslenir ve Authorization başlığını okumaz. Ek yüklemeleri tarafından döndürülen yükleme URL'leri tek bir yükleme için kimlik bilgisinin kendisidir ve Authorization başlığı olmadan kullanılmalıdır.