Applications

An application is an OAuth2 client with one bot account, and a user can own up to 25 of them. The routes on this page need a user session unless they say otherwise. A bot or OAuth2 bearer token on one of those routes gets 403 ACCESS_DENIED. A route that takes an application ID returns 404 UNKNOWN_APPLICATION when the application does not exist and 403 ACCESS_DENIED when you do not own it. The authorization flow and its tokens are on OAuth2.

Application object

The routes for an application you own return this object.

Structure

Field	Type	Description
id	snowflake	The ID of the application
name	string	The name of the application (1-100 characters)
redirect_uris	array[string]	The redirect URIs registered for the application
bot_public	boolean	Whether any eligible user can install the bot
bot_require_code_grant	boolean	Whether installing the bot needs an OAuth2 code grant
client_secret?1	string	The client secret for token exchange, introspection and revocation
bot?2	application bot object	The bot account the application owns

¹ Returned only by Create application and Reset client secret

² Not returned by Reset client secret

Example

{
  "id": "1501314428688998182",
  "name": "Party Parrot",
  "redirect_uris": ["https://example.com/callback"],
  "bot_public": true,
  "bot_require_code_grant": false
}

Application bot object

Each application has one bot account, and the bot's user ID is the same as the application ID.

Structure

Field	Type	Description
id	snowflake	The ID of the bot user
username	string	The username of the bot account
discriminator	string	The four-digit discriminator of the bot account
avatar?	?string	The avatar hash of the bot account
banner?	?string	The banner hash of the bot account
bio	?string	The profile biography of the bot account
token?1	string	The bot token
mfa_enabled?	boolean	Whether the bot account has an authenticator
authenticator_types?	array[integer]	The authenticator types on the bot account
flags	integer	The account's public user flags, including bot flags

¹ Returned only by Create application

Public application object

Anyone can see this version of an application, with or without a credential.

Structure

Field	Type	Description
id	snowflake	The ID of the application
name	string	The name of the application
icon	?string	The avatar hash of the bot account
description	?string	Always null
redirect_uris	array[string]	The redirect URIs registered for the application
scopes	array[string]	The OAuth2 scopes the application can be authorized for
bot_public1	boolean	Whether the requester can install the bot
bot	?application bot object	The bot account, without token, mfa_enabled or authenticator_types
current_user?	?partial user object	The requesting account, or null without a credential

¹ Always true for the application owner

Current bot application object

This is the application that issued the bot token making the request.

Structure

Field	Type	Description
id	snowflake	The ID of the application
name	string	The name of the application
icon	?string	The avatar hash of the bot account
description	?string	The biography of the bot account
bot_public	boolean	Whether any eligible user can install the bot
bot_require_code_grant	boolean	Whether installing the bot needs an OAuth2 code grant
verify_key	string	A placeholder of 64 0 characters
owner	partial user object	The account that owns the application
bot?	application bot object	The bot account, without token
redirect_uris?	array[string]	The redirect URIs registered for the application

Bot profile object

Update bot profile returns this object.

Structure

Field	Type	Description
id	snowflake	The ID of the bot user
username	string	The username of the bot account
discriminator	string	The four-digit discriminator of the bot account
avatar	?string	The avatar hash of the bot account
banner	?string	The banner hash of the bot account
bio	?string	The profile biography of the bot account
flags	integer	The account's public user flags, including bot flags

Bot flags

These bits are in the bot account's flags, and you set them with bot_flags in Update bot profile.

Value	Name	Description
1 << 4	FRIENDLY_BOT	The bot accepts friend requests from users
1 << 5	FRIENDLY_BOT_MANUAL_APPROVAL	The bot needs manual approval for friend requests

Bot token reset object

Reset bot token returns this object.

Structure

Field	Type	Description
token	string	The new bot token
bot	application bot object	The bot account, without token

List owned applications

GET/v1/users/@me/applications

Returns every application the current user owns, without client secrets or bot tokens.

Response

Status	Body	Condition
200	array[application object]	The applications were returned

The rate limit is 60 requests per minute, on the oauth_dev:clients:list bucket.

Get current application

GET/v1/oauth2/applications/@meBot

Returns the same array as List owned applications for a user session, and the current bot application object for a bot token. OAuth2 bearer tokens get 403 ACCESS_DENIED.

Response

Status	Body	Condition
200	array[application object] | current bot application object	The current application data was returned

The rate limit is 60 requests per minute, on the oauth_dev:clients:list bucket.

Get bot application

GET/v1/applications/@meBot

Returns the current bot application object for the bot token in the Authorization header.

Response

Status	Body	Condition
200	current bot application object	The application was returned
401	error response	INVALID_TOKEN when the header is missing, isn't a bot token or the application was deleted

The rate limit is 60 requests per minute, on the oauth_dev:clients:list bucket.

Get public application

GET/v1/oauth2/applications/{id}/publicUnauthenticated

Returns the public application object for any application.

Response

Status	Body	Condition
200	public application object	The application was returned

The rate limit is 60 requests per minute, on the oauth_dev:clients:list bucket.

Create application

POST/v1/oauth2/applications

Creates an application and its bot account, and returns the application object with the client secret and bot token. After this, only the reset routes return them. The bot's username is the application name when it's available, and a random name otherwise.

Request headers

Field	Type	Description
X-Captcha-Token?	string	The solved CAPTCHA token

JSON body

Field	Type	Description
name	string	The name of the application (1-100 characters)
redirect_uris?1	?array[string]	The redirect URIs to register (at most 10, each 1-256 characters)
bot_public?	boolean	Whether any eligible user can install the bot (default true)
bot_require_code_grant?	boolean	Whether installing the bot needs an OAuth2 code grant (default false)

¹ Each URI must be an absolute HTTPS URL. HTTP is allowed for localhost, *.localhost and IP literals

Response

Status	Body	Condition
200	application object	The application and its bot were created
400	error response	MAX_APPLICATIONS when you already own 25 applications
403	error response	Your account is unclaimed2
403	error response	ACCOUNT_VERIFICATION_REQUIRED when the instance needs a verified account and yours is not
403	error response	CONTENT_BLOCKED when the name, a redirect URI or the bot username is blocked
500	error response	BOT_USER_GENERATION_FAILED when no bot username is free

² The error code is UNCLAIMED_ACCOUNT_CANNOT_CREATE_APPLICATIONS

The rate limit is 10 requests per hour, on the oauth_dev:clients:create bucket.

Get application

GET/v1/oauth2/applications/{id}

Returns one application object you own.

Response

Status	Body	Condition
200	application object	The application was returned

The rate limit is 60 requests per minute, on the oauth_dev:clients:list bucket.

Update application

PATCH/v1/oauth2/applications/{id}

Updates an application you own and returns the application object.

JSON body

Field	Type	Description
name?	string	The name of the application (1-100 characters)
redirect_uris?1	?array[string]	The redirect URIs to register (at most 10)
bot_public?	boolean	Whether any eligible user can install the bot
bot_require_code_grant?	boolean	Whether installing the bot needs an OAuth2 code grant

¹ The array replaces the whole set, and null clears it. Each URI follows the same rules as in Create application

Response

Status	Body	Condition
200	application object	The application was updated
403	error response	CONTENT_BLOCKED when the name or a redirect URI is blocked

The rate limit is 30 requests per minute, on the oauth_dev:clients:update::client_id bucket.

Update bot profile

PATCH/v1/oauth2/applications/{id}/bot

Updates the bot account of an application you own and returns the bot profile object. An omitted field stays as it is, and null clears it. The update also clears the bot's display name, and Fluxer sends User Update to the bot's sessions.

JSON body

Field	Type	Description
username?1	string	The username of the bot account (1-32 letters, digits or underscores)
discriminator?2	string | integer	The current discriminator of the bot account
avatar?3	?string	The base64-encoded avatar image
banner?3	?string	The base64-encoded banner image
bio?	?string	The profile biography (0-1024 characters)
bot_flags?4	integer	Bot flags

¹ Changing the username beyond letter case gives the bot a new random discriminator. You can change the username 5 times per 3 hours, and after that the request fails with USERNAME_CHANGED_TOO_MANY_TIMES

² Any value other than the current discriminator fails with BOT_DISCRIMINATOR_CANNOT_BE_CHANGED

³ The image must fit the avatar_max_size limit

⁴ Fluxer sets or clears only the bot flags and ignores other bits

Response

Status	Body	Condition
200	bot profile object	The profile was updated
400	error response	USERNAME_NOT_AVAILABLE when no discriminator is free for the username
403	error response	CONTENT_BLOCKED when the username or biography is blocked
404	error response	BOT_USER_NOT_FOUND when the application has no bot account

The rate limit is 30 requests per minute, on the oauth_dev:clients:update::client_id bucket.

Reset bot token

POST/v1/oauth2/applications/{id}/bot/reset-tokenMFA

Issues a new bot token for an application you own and returns the bot token reset object. You need sudo mode.

The old token stops working at once

Every Gateway session the bot has ends, and the bot can only connect again with the new token.

JSON body

The body is a sudo verification object.

Response

Status	Body	Condition
200	bot token reset object	The token was rotated
404	error response	BOT_USER_NOT_FOUND when the application has no bot account

The rate limit is 10 requests per hour, on the oauth_dev:clients:rotate_secret::client_id bucket.

Reset client secret

POST/v1/oauth2/applications/{id}/client-secret/resetMFA

Issues a new client secret for an application you own and returns the application object with it. You need sudo mode. The old secret stops working at once, and access and refresh tokens already issued stay valid.

JSON body

The body is a sudo verification object.

Response

Status	Body	Condition
200	application object	The client secret was rotated

The rate limit is 10 requests per hour, on the oauth_dev:clients:rotate_secret::client_id bucket.

Delete application

DELETE/v1/oauth2/applications/{id}MFA

Deletes an application you own. You need sudo mode.

Deletion can't be undone

The client secret and bot token stop working. The bot leaves every guild, which sends Guild Member Remove in each one, and its account becomes DeletedUser#0000.

JSON body

The body is a sudo verification object.

Response

Status	Body	Condition
204	empty	The application was deleted

The rate limit is 10 requests per hour, on the oauth_dev:clients:delete::client_id bucket.