Authentication

A major distinguishing feature of user accounts is that you retrieve authentication tokens by logging in through a classic email/password combination. However, the full login & registration flow is quite complex, and involves several steps.

Fingerprints

Discord uses fingerprints to persist experiments throughout the authentication flow. For more information about fingerprints, see the relevant experiment documentation.

If the client is unauthenticated, a fingerprint should be generated using Get Experiment Assignments and included in the X-Fingerprint header as well as any applicable fingerprint JSON parameters until authentication is complete.

Sessions

Discord uses sessions to track the user's authentication state. A session is created when the user logs in and is invalidated when the user logs out or the session expires. Sessions are unique to a single authentication token and keep track of the last location they were used from. Suspicious sessions may be flagged by Discord and lead to the account being locked, requiring the user to reset their password.

The authentication session ID corresponding to the current Gateway session is given in the auth_session_id_hash field in the Ready event. If the current Gateway session's authentication session ever changes (e.g. due to a password reset), the client will receive an Auth Session Change Gateway event.

Auth Session Object

Auth Session Structure

Auth Session Client Info Structure

Example Auth Session

{
  "id_hash": "y3vq9yYww3Y1yAhc4ChuRtCOHADRu0gTPoIU5y3DcS4=",
  "approx_last_used_time": "2024-03-30T21:30:58.100231+00:00",
  "client_info": {
    "os": "Windows",
    "platform": "Discord Client",
    "location": "San Francisco, California, United States"
  }
}

Endpoints

Get Auth Sessions

Returns up to 50 of the user's active authentication sessions.

Response Body

Logout Auth Sessions

Invalidates a list of authentication sessions. Returns a 204 empty response on success.

JSON Params

Login

The login process is the first step in authenticating a user.

To log in, a client must first use the Login Account endpoint with the user's email/phone number and password. If the user has multi-factor authentication enabled, the client must use the Verify MFA Login endpoint to complete the login process after a successful response.

If a known JSON error code is returned, the client must handle the error accordingly (e.g. prompt the user to undelete their account or verify their phone number). If a form body error is returned, the client should display the error message to the user.

Once the user is logged in, the client should store the authentication token to avoid having to log in again in the future.

Passwordless Login

An alternative to the traditional email/password login flow is the WebAuthn Conditional UI flow. This allows users to log in using an WebAuthn device (e.g. a security key) instead of a password.

To use this flow, the client must first generate a challenge using the Start Passwordless Login endpoint. After the user completes the WebAuthn challenge, the client must use the Finish Passwordless Login endpoint to complete the login process. Using this flow, you must still take care to handle any errors as outlined above.

Authentication Handoff

The handoff process is used to securely transfer the user's authentication state between two clients, commonly used to authenticate the Discord website from a native client and vice-versa.

To handoff authentication to another client, the source client must first use the Create Handoff Token endpoint to generate a handoff token. The token should then be passed to the target client, which can use the Exchange Handoff Token endpoint to retrieve a new authentication token.

Note that handoff tokens are single-use and valid only for the IP address they were generated from.

Endpoints

Login Account

Retrieves an authentication token for the given credentials.

JSON Params

¹ If you get an account disabled (20013) or marked for deletion (20011) JSON error code, you can undelete the account by setting this parameter.

Login Source

Where a login is initiated from outside of the normal login flow.

Response Body

Login Settings Structure

A partial settings object to bootstrap the client with.

Login Required Action Type

Actions the user must complete after a successful login.

Example Response (Completed)

{
  "user_id": "852892297661906993",
  "token": "ODUyODkyMjk3NjYxOTA2OTkz.GX5Xdp.22jsdSqEiHLUYEJSsjeq_vJKLpOofd5QMksqw32e",
  "user_settings": {
    "locale": "en-US",
    "theme": "dark"
  },
  "required_actions": ["update_password"]
}

Example Response (MFA Required)

{
  "user_id": "852892297661906993",
  "mfa": true,
  "sms": true,
  "ticket": "ODUyODkyMjk3NjYxOTA2OTkz.H2Rpq0.WrhGhYEhM3lHUPN61xF6JcQKwVutk8fBvcoHjo",
  "backup": true,
  "totp": true,
  "webauthn": "{\"publicKey\":{\"challenge\":\"a8a1cHP7_zYheggFG68zKUkl8DwnEqfKvPE-GOMvhss\",\"timeout\":60000,\"rpId\":\"discord.com\",\"allowCredentials\":[{\"type\":\"public-key\",\"id\":\"izrvF80ogrfg9dC3RmWWwW1VxBVBG0TzJVXKOJl__6FvMa555dH4Trt2Ub8AdHxNLkQsc0unAGcn4-hrJHDKSO\"}],\"userVerification\":\"preferred\"}}",
  "required_actions": ["update_password"]
}

Verify MFA Login

Verifies a multi-factor login and retrieves an authentication token using the specified authenticator type.

JSON Params

¹ For WebAuthn authentication, the code parameter should be a stringified JSON object of the public key credential response.

Response Body

Example Response (Completed)

{
  "token": "ODUyODkyMjk3NjYxOTA2OTkz.GX5Xdp.22jsdSqEiHLUYEJSsjeq_vJKLpOofd5QMksqw32e",
  "user_settings": {
    "locale": "en-US",
    "theme": "dark"
  }
}

Start Passwordless Login

Generates a challenge to start the conditional UI flow for WebAuthn login.

Response Body

Example Response

{
  "challenge": "{\"publicKey\":{\"challenge\":\"sLPruFUWBzowZjYy5d2caF2067pw44butrN0iHm_8k4\",\"timeout\":60000,\"rpId\":\"discord.com\",\"allowCredentials\":[],\"userVerification\":\"required\",\"extensions\":{\"uvm\":true}},\"mediation\":\"conditional\"}",
  "ticket": "b9f98b82-c3a7-49b6-b881-f83418fa2dbe"
}

Finish Passwordless Login

Retrieves an authentication token for the given WebAuthn credentials.

JSON Params

Response Body

Example Response

{
  "user_id": "852892297661906993",
  "token": "ODUyODkyMjk3NjYxOTA2OTkz.GX5Xdp.22jsdSqEiHLUYEJSsjeq_vJKLpOofd5QMksqw32e",
  "user_settings": {
    "locale": "en-US",
    "theme": "dark"
  },
  "required_actions": ["update_password"]
}

Authorize IP Address

Authorizes the client's IP address for login. Returns a 204 empty response on success.

JSON Params

Create Handoff Token

Creates a handoff token to transfer the user's authentication state to another client.

JSON Params

Response Body

Exchange Handoff Token

Exchanges a handoff token for an authentication token. Handoff tokens can only be exchanged once and are only valid from the same IP address they were created from.

JSON Params

Response Body

Register

Potential users must register an account before they are able to use most of the platform.

The full registration process involves choosing a username & display name, providing an email address or phone number, setting a password, and providing a date of birth. However, the client can choose to skip some of these steps to provide a more streamlined registration experience, such as when viewing an invite or gift code.

To register, the client should first retrieve the user's location metadata to determine whether explicit consent is required. Then, they can use the Register Account endpoint to create a new account with the provided credentials. Throughout the process, they can use the Get Unique Username Suggestions to get username suggestions for the user's display name and Get Unique Username Eligibility endpoints to validate the username's availability.

Once the user is registered, the client should store the authentication token to avoid having to log in again in the future.

Phone Registration

Clients can alternatively register an account using a phone number. To do so, the client must first use the Register by Phone Number endpoint to send a verification code to the user's phone number. Then, the client must verify the phone number using the received code before completing the registration using the Register Account endpoint as usual.

Endpoints

Register Account

Creates a new account and retrieves an authentication token for the given credentials.

JSON Params

¹ One of username or global_name must be provided. A valid username can be retrieved using the Get Unique Username Suggestions endpoint and validated using the Get Unique Username Eligibility endpoint. See the Usernames and Nicknames section for more information on username restrictions.

² This value should be set to the same fingerprint used throughout the authentication flow. Upon valid registration, the new account will share the same ID as the fingerprint to ensure experiment continuity.

³ Upon valid registration, this invite code will automatically be accepted.

⁴ Clients can determine whether explicit consent is required by using the Get Location Metadata endpoint.

Response Body

Example Response

{
  "token": "ODUyODkyMjk3NjYxOTA2OTkz.GX5Xdp.22jsdSqEiHLUYEJSsjeq_vJKLpOofd5QMksqw32e",
  "show_verification_form": true
}

Register by Phone Number

Sends a verification code to the user's phone number to register an account. Returns a 204 empty response on success. The verification code should be first used to verify the phone number before completing the registration.

JSON Params

Get Location Metadata

Returns the location metadata for the user's IP address.

Response Body

Promotional Email Metadata Structure

Example Response

{
  "consent_required": false,
  "country_code": "CA",
  "promotional_email_opt_in": {
    "required": true,
    "pre_checked": false
  }
}

Get Unique Username Suggestions

Returns a suggested unique username string for the user to register with.

Query String Params

Response Body

Example Response

{ "username": "gnarp.gnap" }

Get Unique Username Eligibility

Checks whether a unique username is available for the user to register with.

JSON Params

Response Body

Example Response

{ "taken": true }

Logout

To log out, the client must use the Logout endpoint with the user's authentication token. This is used to invalidate the token and prevent further push notifications from being sent to the client. See the push notifications section for more information.

Endpoints

Logout

Invalidates the given authentication session and unregisters the provided push notification token.

JSON Params

¹ VOIP-specific push notification tokens are only used with PushKit on iOS.

Account Recovery

If a user has forgotten their password, they can reset it using either their email address or phone number. To initiate a password reset, the client should use the Forgot Password endpoint.

To complete the password reset, the user must either retrieve the password reset token from their email or by verifying their phone number. Then, the client can use the Reset Password endpoint to set a new password.

Endpoints

Forgot Password

Initiates the password reset process for the given email or phone number. Returns a 204 empty response on success.

JSON Params

Reset Password

Resets the user's password and retrieves an authentication token.

JSON Params

¹ For WebAuthn authentication, the code parameter should be a stringified JSON object of the public key credential response.

Response Body

Example Response (Completed)

{ "token": "ODUyODkyMjk3NjYxOTA2OTkz.GX5Xdp.22jsdSqEiHLUYEJSsjeq_vJKLpOofd5QMksqw32e" }

Example Response (MFA Required)

{
  "user_id": "852892297661906993",
  "mfa": true,
  "sms": true,
  "ticket": "ODUyODkyMjk3NjYxOTA2OTkz.H2Rpq0.WrhGhYEhM3lHUPN61xF6JcQKwVutk8fBvcoHjo",
  "backup": true,
  "totp": true,
  "webauthn": "{\"publicKey\":{\"challenge\":\"a8a1cHP7_zYheggFG68zKUkl8DwnEqfKvPE-GOMvhss\",\"timeout\":60000,\"rpId\":\"discord.com\",\"allowCredentials\":[{\"type\":\"public-key\",\"id\":\"izrvF80ogrfg9dC3RmWWwW1VxBVBG0TzJVXKOJl__6FvMa555dH4Trt2Ub8AdHxNLkQsc0unAGcn4-hrJHDKSO\"}],\"userVerification\":\"preferred\"}}"
}

MFA Verification

In some cases, you may be required to verify your identify using multi-factor authentication before performing certain sensitive actions. When this occurs, you'll receive a 401 unauthorized error with a special error response body:

MFA Required Response Structure

MFA Verification Request Structure

MFA Method Structure

Authenticator Type

¹ The user password is used to authenticate in certain cases if the user has not enabled any other MFA methods.

Example MFA Required Response

{
  "message": "Two factor is required for this operation",
  "code": 60003,
  "mfa": {
    "ticket": "ODUyODkyMjk3NjYxOTA2OTkz.H2Rpq0.WrhGhYEhM3lHUPN61xF6JcQKwVutk8fBvcoHjo",
    "methods": [
      {
        "type": "webauthn",
        "challenge": "{\"publicKey\":{\"challenge\":\"a8a1cHP7_zYheggFG68zKUkl8DwnEqfKvPE-GOMvhss\",\"timeout\":60000,\"rpId\":\"discord.com\",\"allowCredentials\":[{\"type\":\"public-key\",\"id\":\"izrvF80ogrfg9dC3RmWWwW1VxBVBG0TzJVXKOJl__6FvMa555dH4Trt2Ub8AdHxNLkQsc0unAGcn4-hrJHDKSO\"}],\"userVerification\":\"preferred\"}}"
      },
      {
        "type": "totp",
        "backup_codes_allowed": true
      },
      {
        "type": "sms"
      },
      {
        "type": "backup"
      }
    ]
  }
}

To verify, you must use the Verify MFA endpoint with the ticket retrieved from the error response. The retrieved verification JWT can then be inserted into the X-Discord-MFA-Authorization header and the original request can be retried.

Upon successful elevation, the verification JWT will be returned in a __Secure-recent_mfa cookie that temporary bypasses MFA for the next 5 minutes.

Endpoints

Verify MFA

Verifies a user's identity using multi-factor authentication. On success, returns a cookie that can be used to bypass MFA for the next 5 minutes.

JSON Params

¹ For WebAuthn authentication, the data parameter should be a stringified JSON object of the public key credential response.

Response Body

Example Response

{
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJpYXQiOjE3MTA4MDY4MDQsIm5iZiI6MTcxMDgwNjgwNCwiZXhwIjoxNzEwODA3MTA0LCJpc3MiOiJ1cm46ZGlzY29yZC1hcGkiLCJhdWQiOiJ1cm46ZGlzY29yZC1tZmEtcmVwcm9tcHQiLCJ1c2VyIjo4NTI4OTIyOTc2NjE5MDY5OTN9.vOCStK0Aj873VaF_cLmSlcnAfw7SO0jrwSeCpkSUvO3li-1jxzwewxY4Ak4fyZvb6VeJtSW-r8_Pfw8HTj8P6w"
}

Send MFA SMS

Sends a multi-factor authentication code to the user's phone number for verification.

JSON Params

Response Body

Example Response

{ "phone": "+*******0085" }