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.

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.

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.

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

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

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

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.

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.

Retrieves an authentication token for the given credentials.

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

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

A partial settings object to bootstrap the client with.

Actions the user must complete after a successful login.

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

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

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

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

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

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

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

Retrieves an authentication token for the given WebAuthn credentials.

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

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

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.

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.

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

¹ 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.

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

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.

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

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

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

{ "username": "gnarp.gnap" }

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

{ "taken": true }

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.

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

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

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.

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

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

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

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

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

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:

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

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

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.

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

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

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

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