Applications¶

An application is an OAuth2 client owned by one user account, and every bot account belongs to one application. Creating an application always creates its bot account too. A user owns at most 25 applications. The authorisation code grant, the scopes, and the tokens issued to third-party clients belong to the OAuth2 resource. For a walkthrough, see Creating a bot.

Access rules¶

The management routes are user-only: they require a user session token, and a valid bot token is rejected with 403 ACCESS_DENIED (an invalid one with 401). Get public application needs no credential. Get bot application accepts only a bot token, and Get current application accepts either.

Only the owner can read or change an application. Another account receives 403 FORBIDDEN.

The credential-rotation routes and Delete application require sudo mode. Put the proof in the JSON body (password, mfa_code, or sudo_proof), or call them from a session that holds a sudo grant from Grant sudo mode. A missing proof returns 403 SUDO_MODE_REQUIRED.

Bot tokens¶

A bot token is the application ID, a full stop, and a secret of 32 random bytes encoded as base64url:

1501314428688998182.q0lPd3Jm3wX8Yv1lS4a2bQ6uK9tE7nZcR5hJ0mAoVfI

Send it as Authorization: Bot <token>. The bot user's ID is always equal to the application ID. See Authentication.

Application object¶

The application as its owner sees it.

Structure¶

Example¶

{
  "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
  }
}

Application bot object¶

The bot account an application owns.

Structure¶

Bot flags¶

These bits live in the bot's user flags. Update bot profile can change only these two bits. A client MUST ignore bits it does not recognise.

Public application object¶

The application as any caller sees it, including a caller that sends no credential.

Structure¶

Current bot application object¶

The application behind a bot token, as returned to that token.

Structure¶

Bot profile object¶

Returned by Update bot profile.

Structure¶

Bot token reset object¶

Returned by Reset bot token.

Structure¶

List owned applications¶

GET /users/@me/applications

Returns an array of every application object the current user owns. Requires a user session token; a request with a Bot credential returns 403 FORBIDDEN. No entry has a client secret or bot token. The list is not paginated.

Rate limit¶

60 requests per minute for each account, on the oauth_dev:clients:list bucket.

Get current application¶

GET /oauth2/applications/@me

Returns the caller's applications, selected by credential type:

• A user session returns the same array as List owned applications.
• A bot token returns the current bot application object.

Rate limit¶

60 requests per minute for each user or bot, on the oauth_dev:clients:list bucket.

Get bot application¶

GET /applications/@me

Returns the current bot application object for the presented bot token. Only Authorization: Bot <token> is accepted.

Response¶

Every rejection is the same, so a caller cannot tell a malformed token from one whose application was deleted. A bot can use this route to validate its token on start-up.

Get public application¶

GET /oauth2/applications/{id}/public

Returns the public application object. Authentication is not required. A valid user session fills in current_user, and the owner sees bot_public: true.

Path parameters¶

Response¶

Rate limit¶

60 requests per minute for each client, on the oauth_dev:clients:list bucket.

Create application¶

POST /oauth2/applications

Creates an application together with its bot account. Returns the application object with the initial client_secret and, in bot.token, the initial bot token.

The route is CAPTCHA-gated: when the instance has a CAPTCHA provider, a missing X-Captcha-Token returns 400 CAPTCHA_REQUIRED and a rejected one returns 400 INVALID_CAPTCHA. See CAPTCHA handling.

Request headers¶

JSON body¶

Redirect URIs are stored exactly as given. Authorise application and the token exchange compare them byte for byte, so register the exact string your callback uses, preferably with https.

Response¶

Side effects¶

The bot's username is derived from the application name: ASCII letters, digits, and _ are kept, spaces, -, and . become _, and the result is cut to 32 characters. When that leaves fewer than 2 characters, or the name has no free discriminator, a random name of the form Bot plus 8 letters and digits is used. The discriminator is the lowest free number for that username. The bot starts with no avatar, banner, or biography.

Rate limit¶

10 requests per hour for each account, on the oauth_dev:clients:create bucket.

Example¶

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"]}'

Get application¶

GET /oauth2/applications/{id}

Returns one application object. Only the owner can read it.

Path parameters¶

Response¶

Rate limit¶

60 requests per minute for each account, on the oauth_dev:clients:list bucket.

Update application¶

PATCH /oauth2/applications/{id}

Updates an application and returns the resulting application object. Only the owner can update it. An omitted field is left unchanged.

Path parameters¶

JSON body¶

Removing a redirect URI affects new authorisation requests only. A code already issued for that URI still exchanges with it, and existing tokens are unaffected. Neither the client secret nor the bot token changes.

Response¶

Rate limit¶

30 requests per minute for each application, on the oauth_dev:clients:update bucket, shared with Update bot profile.

Update bot profile¶

PATCH /oauth2/applications/{id}/bot

Updates the application's bot account and returns the bot profile object. Only the owner can update it.

Path parameters¶

JSON body¶

An image must be PNG, JPEG, GIF, or WebP and between 1 byte and 8 MiB after decoding. An omitted avatar, banner, or bio leaves the stored value unchanged; only null removes it.

When the username changes, the bot keeps its discriminator if it is free for the new name, and otherwise gets the lowest free one. A name with no free discriminator returns 400.

The update always clears the bot's display name, so a bot is always shown by its username.

Response¶

Rate limit¶

30 requests per minute for each application, on the oauth_dev:clients:update bucket, shared with Update application.

Reset bot token¶

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

Rotates the bot token and returns the bot token reset object. The caller must own the application and prove sudo mode.

Path parameters¶

JSON body¶

Optional sudo verification fields: password, mfa_code, or sudo_proof. Send an empty body when the session holds a sudo grant.

Response¶

The bot's guild and group DM memberships are unchanged.

Rate limit¶

10 requests per hour for each application, on the oauth_dev:clients:rotate_secret bucket, shared with Reset client secret.

Reset client secret¶

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

Rotates the OAuth2 client secret and returns the application object with the new client_secret. The caller must own the application and prove sudo mode.

Path parameters¶

JSON body¶

Optional sudo verification fields, as for Reset bot token.

Response¶

Token exchange, introspection, and revocation stop accepting the previous secret immediately. Existing access and refresh tokens stay valid.

Rate limit¶

10 requests per hour for each application, on the oauth_dev:clients:rotate_secret bucket, shared with Reset bot token.

Delete application¶

DELETE /oauth2/applications/{id}

Deletes an application and retires its bot account. Returns 204. The caller must own the application and prove sudo mode.

Path parameters¶

JSON body¶

Optional sudo verification fields, as for Reset bot token.

Response¶

After deletion, the token, introspection, and revocation routes reject the client, and Get current OAuth2 authorisation returns 401 for the application's access tokens. The bot's messages remain, attributed to the anonymised account.

Rate limit¶

10 requests per hour for each application, on the oauth_dev:clients:delete bucket.