Uygulamalar¶

Uygulama, tek bir kullanıcı hesabının sahip olduğu bir OAuth2 istemcisidir ve her bot hesabı bir uygulamaya aittir. Bir uygulama oluşturmak her zaman onun bot hesabını da oluşturur. Bir kullanıcı en fazla 25 uygulamaya sahip olabilir. Yetkilendirme kodu akışı (authorisation code grant), kapsamlar ve üçüncü taraf istemcilere verilen token'lar OAuth2 kaynağına aittir. Adım adım anlatım için bkz. Bot oluşturma.

Erişim kuralları¶

Yönetim yolları yalnızca kullanıcıya yöneliktir: kullanıcı oturumu token'ı gerektirirler; geçerli bir bot token'ı 403 ACCESS_DENIED ile (geçersiz olanı 401 ile) reddedilir. Herkese açık uygulamayı getir hiçbir kimlik bilgisi gerektirmez. Bot uygulamasını getir yalnızca bot token'ı kabul eder; Geçerli uygulamayı getir ise ikisini de kabul eder.

Bir uygulamayı yalnızca sahibi okuyabilir veya değiştirebilir. Başka bir hesap 403 FORBIDDEN alır.

Kimlik bilgisi yenileme yolları ve Uygulamayı sil sudo kipi gerektirir. Kanıtı JSON gövdesine koyun (password, mfa_code veya sudo_proof) ya da bu yolları Sudo kipi ver ile alınmış bir sudo yetkisine sahip bir oturumdan çağırın. Kanıt eksikse 403 SUDO_MODE_REQUIRED döner.

Bot token'ları¶

Bot token'ı; uygulama kimliği, bir nokta ve base64url olarak kodlanmış 32 rastgele bayttan oluşan bir gizli değerdir:

1501314428688998182.q0lPd3Jm3wX8Yv1lS4a2bQ6uK9tE7nZcR5hJ0mAoVfI

Onu Authorization: Bot <token> olarak gönderin. Bot kullanıcısının kimliği her zaman uygulama kimliğine eşittir. Bkz. Kimlik doğrulama.

Uygulama nesnesi¶

Uygulamanın, sahibinin gördüğü hâli.

Yapı¶

Örnek¶

{
  "id": "1501314428688998182",
  "name": "Party Parrot",
  "redirect_uris": ["https://example.com/callback"],
  "bot_public": true,
  "bot_require_code_grant": false,
  "bot": {
    "id": "1501314428688998182",
    "username": "Party_Parrot",
    "discriminator": "0001",
    "avatar": null,
    "banner": null,
    "bio": null,
    "mfa_enabled": false,
    "authenticator_types": [],
    "flags": 0
  }
}

Uygulama botu nesnesi¶

Bir uygulamanın sahip olduğu bot hesabı.

Yapı¶

Bot bayrakları¶

Bu bitler botun kullanıcı flags değerinde bulunur. Bot profilini güncelle yalnızca bu iki biti değiştirebilir. İstemci tanımadığı bitleri yok saymalıdır (MUST).

Herkese açık uygulama nesnesi¶

Uygulamanın, kimlik bilgisi göndermeyen çağıranlar dahil herhangi bir çağıranın gördüğü hâli.

Yapı¶

Geçerli bot uygulaması nesnesi¶

Bir bot token'ının arkasındaki uygulama; o token'a döndürüldüğü hâliyle.

Yapı¶

Bot profili nesnesi¶

Bot profilini güncelle tarafından döndürülür.

Yapı¶

Bot token'ı sıfırlama nesnesi¶

Bot token'ını sıfırla tarafından döndürülür.

Yapı¶

Sahip olunan uygulamaları listele¶

GET /users/@me/applications

Geçerli kullanıcının sahip olduğu tüm uygulama nesnelerinin bir dizisini döndürür. Kullanıcı oturumu token'ı gerektirir; Bot kimlik bilgisiyle yapılan bir istek 403 FORBIDDEN döndürür. Hiçbir girdide istemci gizli anahtarı veya bot token'ı yoktur. Liste sayfalanmaz.

Hız sınırı¶

oauth_dev:clients:list kovasında, her hesap için dakikada 60 istek.

Geçerli uygulamayı getir¶

GET /oauth2/applications/@me

Çağıranın uygulamalarını, kimlik bilgisi türüne göre seçerek döndürür:

• Kullanıcı oturumu, Sahip olunan uygulamaları listele ile aynı diziyi döndürür.
• Bot token'ı, geçerli bot uygulaması nesnesini döndürür.

Hız sınırı¶

oauth_dev:clients:list kovasında, her kullanıcı veya bot için dakikada 60 istek.

Bot uygulamasını getir¶

GET /applications/@me

Sunulan bot token'ı için geçerli bot uygulaması nesnesini döndürür. Yalnızca Authorization: Bot <token> kabul edilir.

Yanıt¶

Her ret aynıdır; bu yüzden çağıran, hatalı biçimli bir token'ı uygulaması silinmiş bir token'dan ayırt edemez. Bir bot bu yolu açılışta token'ını doğrulamak için kullanabilir.

Herkese açık uygulamayı getir¶

GET /oauth2/applications/{id}/public

Herkese açık uygulama nesnesini döndürür. Kimlik doğrulama gerekmez. Geçerli bir kullanıcı oturumu current_user alanını doldurur; sahip ise bot_public: true görür.

Yol parametreleri¶

Yanıt¶

Hız sınırı¶

oauth_dev:clients:list kovasında, her istemci için dakikada 60 istek.

Uygulama oluştur¶

POST /oauth2/applications

Bot hesabıyla birlikte bir uygulama oluşturur. İlk client_secret değerini ve bot.token içinde ilk bot token'ını içeren uygulama nesnesini döndürür.

Yol CAPTCHA korumalıdır: örnekte (instance) bir CAPTCHA sağlayıcısı varsa, eksik bir X-Captcha-Token 400 CAPTCHA_REQUIRED, reddedilen bir token ise 400 INVALID_CAPTCHA döndürür. Bkz. CAPTCHA işleme.

İstek başlıkları¶

JSON gövdesi¶

Yönlendirme URI'leri tam olarak verildiği gibi saklanır. Uygulamayı yetkilendir ve token değişimi bunları bayt bayt karşılaştırır; bu yüzden geri çağırma adresinizin kullandığı dizeyi birebir, tercihen https ile kaydedin.

Yanıt¶

Yan etkiler¶

Botun kullanıcı adı uygulama adından türetilir: ASCII harfler, rakamlar ve _ korunur; boşluklar, - ve . ise _ olur ve sonuç 32 karaktere kesilir. Bu işlem 2 karakterden az bırakırsa veya adın boş bir ayırt edicisi yoksa, Bot artı 8 harf ve rakamdan oluşan rastgele bir ad kullanılır. Ayırt edici, o kullanıcı adı için boştaki en küçük sayıdır. Bot avatar, afiş veya biyografi olmadan başlar.

Hız sınırı¶

oauth_dev:clients:create kovasında, her hesap için saatte 10 istek.

Örnek¶

curl -X POST https://tebhos.com/api/v1/oauth2/applications \
  -H "Authorization: Bearer <session token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Party Parrot", "redirect_uris": ["https://example.com/callback"]}'

Uygulamayı getir¶

GET /oauth2/applications/{id}

Tek bir uygulama nesnesi döndürür. Yalnızca sahibi okuyabilir.

Yol parametreleri¶

Yanıt¶

Hız sınırı¶

oauth_dev:clients:list kovasında, her hesap için dakikada 60 istek.

Uygulamayı güncelle¶

PATCH /oauth2/applications/{id}

Bir uygulamayı günceller ve sonuçtaki uygulama nesnesini döndürür. Yalnızca sahibi güncelleyebilir. Gönderilmeyen alanlar değiştirilmeden bırakılır.

Yol parametreleri¶

JSON gövdesi¶

Bir yönlendirme URI'sini kaldırmak yalnızca yeni yetkilendirme isteklerini etkiler. O URI için zaten verilmiş bir kod onunla hâlâ değiştirilebilir ve mevcut token'lar etkilenmez. Ne istemci gizli anahtarı ne de bot token'ı değişir.

Yanıt¶

Hız sınırı¶

oauth_dev:clients:update kovasında, her uygulama için dakikada 30 istek; Bot profilini güncelle ile paylaşılır.

Bot profilini güncelle¶

PATCH /oauth2/applications/{id}/bot

Uygulamanın bot hesabını günceller ve bot profili nesnesini döndürür. Yalnızca sahibi güncelleyebilir.

Yol parametreleri¶

JSON gövdesi¶

Görsel PNG, JPEG, GIF veya WebP olmalı ve kod çözüldükten sonra 1 bayt ile 8 MiB arasında olmalıdır. Gönderilmeyen bir avatar, banner veya bio saklanan değeri değiştirmez; yalnızca null onu kaldırır.

Kullanıcı adı değiştiğinde bot, yeni ad için boştaysa ayırt edicisini korur; aksi hâlde boştaki en küçük ayırt ediciyi alır. Boş ayırt edicisi olmayan bir ad 400 döndürür.

Güncelleme botun görünen adını her zaman temizler; böylece bot her zaman kullanıcı adıyla gösterilir.

Yanıt¶

Hız sınırı¶

oauth_dev:clients:update kovasında, her uygulama için dakikada 30 istek; Uygulamayı güncelle ile paylaşılır.

Bot token'ını sıfırla¶

POST /oauth2/applications/{id}/bot/reset-token

Bot token'ını yeniler ve bot token'ı sıfırlama nesnesini döndürür. Çağıran uygulamanın sahibi olmalı ve sudo kipini kanıtlamalıdır.

Yol parametreleri¶

JSON gövdesi¶

İsteğe bağlı sudo doğrulama alanları: password, mfa_code veya sudo_proof. Oturum bir sudo yetkisine sahipse boş bir gövde gönderin.

Yanıt¶

Botun sunucu ve grup DM üyelikleri değişmez.

Hız sınırı¶

oauth_dev:clients:rotate_secret kovasında, her uygulama için saatte 10 istek; İstemci gizli anahtarını sıfırla ile paylaşılır.

İstemci gizli anahtarını sıfırla¶

POST /oauth2/applications/{id}/client-secret/reset

OAuth2 istemci gizli anahtarını yeniler ve yeni client_secret değerini içeren uygulama nesnesini döndürür. Çağıran uygulamanın sahibi olmalı ve sudo kipini kanıtlamalıdır.

Yol parametreleri¶

JSON gövdesi¶

Bot token'ını sıfırla ile aynı şekilde isteğe bağlı sudo doğrulama alanları.

Yanıt¶

Token değişimi, token inceleme (introspection) ve iptal işlemleri önceki gizli anahtarı hemen kabul etmeyi bırakır. Mevcut erişim ve yenileme token'ları geçerli kalır.

Hız sınırı¶

oauth_dev:clients:rotate_secret kovasında, her uygulama için saatte 10 istek; Bot token'ını sıfırla ile paylaşılır.

Uygulamayı sil¶

DELETE /oauth2/applications/{id}

Bir uygulamayı siler ve bot hesabını emekliye ayırır. 204 döndürür. Çağıran uygulamanın sahibi olmalı ve sudo kipini kanıtlamalıdır.

Yol parametreleri¶

JSON gövdesi¶

Bot token'ını sıfırla ile aynı şekilde isteğe bağlı sudo doğrulama alanları.

Yanıt¶

Silmeden sonra token, token inceleme ve iptal yolları istemciyi reddeder; Geçerli OAuth2 yetkilendirmesini getir ise uygulamanın erişim token'ları için 401 döndürür. Botun mesajları, anonimleştirilmiş hesaba atfedilmiş olarak kalır.

Hız sınırı¶

oauth_dev:clients:delete kovasında, her uygulama için saatte 10 istek.