Discord
Implemented flow
The mock implements the OAuth 2.0 authorization code flow for user sign-in:
authorization, code exchange, /users/@me profile lookup, token refresh and
revocation. PKCE is supported with S256.
Discord's OIDC flow is not implemented: openid is accepted but produces no ID
token, and OIDC userinfo is not served. Bot installation, webhooks, app installs,
implicit and client credentials flows, and general Discord APIs are not modeled.
Accepting their scopes does not perform those actions.
For reference, see Discord OAuth2 flows and scopes.
Using the connector
// Better Auth: pass the same options you give socialProviders.discordimport { mockDiscord } from "@mockatoo/connect-better-auth";const discord = { clientId: process.env.DISCORD_CLIENT_ID!, clientSecret: process.env.DISCORD_CLIENT_SECRET! };export const auth = betterAuth({ socialProviders: process.env.NODE_ENV === "production" ? { discord } : {}, plugins: process.env.NODE_ENV === "production" ? [] : [mockDiscord(discord)],});// Auth.js: declare Discord's issuer, or Auth.js refuses the iss Discord sendsimport Discord from "next-auth/providers/discord";import { MockDiscord } from "@mockatoo/connect-authjs";const discord = { issuer: "https://discord.com" };providers: [process.env.NODE_ENV === "production" ? Discord(discord) : MockDiscord(discord)],- Request
identifyfor a profile andemailfor email and verification status. A Discord account registered with a phone number hasemail: nullandverified: falseeven with theemailscope; useyou+noemail@example.comto test this. Better Auth rejects the account withemail_not_found; Auth.js signs in without an email. Handle a missing display name (global_name: null). - Discord includes an issuer in authorization responses. Auth.js needs
issuer: "https://discord.com"on the production provider; the connector replaces it with the mock issuer. prompt=nonepermits sign-in, but the mock still shows consent every time.- Token responses include rotating refresh tokens. Each refresh token works once; refreshing invalidates the access token issued alongside it. Revoking either token ends the whole authorization.
- Only scopes requested in the current sign-in are granted; the mock does not accumulate earlier permissions. Users have default avatars and modern usernames; custom avatars and legacy discriminators are not exercised.
Special test addresses
Log in as you+<tag>@example.com with your own account's password to get a distinct, stable test user. Tags combine with dots, such as you+hd.unverified@example.com. Any other tag, such as you+1@example.com, is just another user; see Email tags.
| Tag | Behavior | |
|---|---|---|
unverified | email_verified: false (GitHub: primary email verified: false; Discord: verified: false; LinkedIn: "false" in the ID token) | Example |
renamed | Same user ID (sub, Microsoft oid, GitHub, Discord, X and Facebook id) as the address without +renamed, different email | Example |
noname | No name (Google: also no given_name/family_name; GitHub: name: null; Discord: global_name: null) | Example |
noemail | No email claim, like an account without a mailbox (Discord: email: null and verified: false; LinkedIn: a member who signed up with a phone number; X: no confirmed_email; Facebook: the user declines the email permission, which debug_token's scopes then leave out) | Example |
revoked | Sign-in works; every refresh returns invalid_grant (GitHub: bad_refresh_token, and only with offline_access; X: invalid_request) | Example |
badcode | The code exchange fails (invalid_grant; GitHub: bad_verification_code; LinkedIn and X: invalid_request; Facebook: Invalid verification code format.) | Example |
down | The token endpoint returns 503 | Example |
flaky | The first exchange of each code returns 503; a retry succeeds | Example |
slow | Token responses are delayed (10 seconds) | Example |
Known differences
This provider
| Difference | Effect |
|---|---|
Better Auth hardcodes discord.com, so mockDiscord() contains a copy of Better Auth's profile lookup and avatar URL code with the URL changed. | Hides changes in a newer Better Auth until the copy is updated. |
Every user has the profile of an account made after Discord's 2023 username change: discriminator is "0" and there is no custom avatar, so apps link Discord's real default avatar image. There are no legacy name#1234 users, animated avatars, banners or Nitro users. | Hides problems in custom-avatar URLs and code that still reads the discriminator. |
A token covers only the scopes asked for at that sign-in. A Discord token covers every scope the user has granted the app, so after one email sign-in, an identify-only sign-in still returns the email. | Breaks code that relies on scopes granted at an earlier sign-in. |
The openid scope is accepted, but no ID token is issued and /api/oauth2/userinfo isn't served. Discord, though it doesn't document it, returns an id_token for openid (iss: https://discord.com, aud: [client ID], one-hour exp, auth_time, at_hash, sub; no email or name claims, and none on refresh) and serves OIDC userinfo. | Breaks an app that signs in with Discord's OIDC. |
Nothing is rate limited. Discord answers too many requests with 429 and a retry_after. | Hides missing retry handling. |
Only user sign-in with the authorization code grant is modeled. The implicit grant (response_type=token), client credentials, adding a bot (bot scope, permissions, guild_id), webhook.incoming and app installs (integration_type) aren't: their scopes are accepted but nothing else happens. | Breaks apps that add a bot or webhook during sign-in. |
Shared mock limits
| Difference | Effect |
|---|---|
| ID tokens are issued to the shared mock client. Native bundle IDs and native client registrations are not modeled. | Hides a native audience setting that does not match your production registration. |
Refresh tokens do not expire from age or inactivity, even when a response advertises refresh_token_expires_in. Rotation and revocation still apply where supported; +revoked forces refresh failure. | Hides failures after long periods without sign-in. Use +revoked to exercise expired or revoked grant handling. |
Any http/https callback URL is accepted, including localhost. Apple refuses http and localhost, and Microsoft refuses http except for localhost, whatever the app registered. | Hides a callback URL the real provider refuses outright. |
Everyone uses one shared client (mockatoo / mockatoo-secret). The connectors replace your production client ID and secret, Apple's signed client secret, and Microsoft's client assertion. | Hides wrong production credentials or a broken client-secret setup. |
The login form and the consent screen appear on every sign-in; there is no remembered session. prompt=none fails for Google (interaction_required) and Microsoft (login_required), and Discord and LinkedIn, which skip consent for a returning user (LinkedIn even with prompt=consent), always ask again. | Breaks silent sign-in that works with a real signed-in user. |
Issuers and signing keys are the mock's (for example https://app.mockatoo.globalunderdog.com/google, not https://accounts.google.com). Discord's authorization responses carry iss=https://app.mockatoo.globalunderdog.com/discord, not https://discord.com. | Breaks code that hardcodes a real issuer or key URL. |
Tokens are only valid at the mock. Real provider APIs (Google APIs, Microsoft Graph, GitHub's api.github.com, Discord's discord.com/api, LinkedIn's api.linkedin.com, X's api.x.com, Facebook's graph.facebook.com) reject them, and the mock doesn't serve those APIs beyond what sign-in needs. | Breaks app features that call the provider's API after sign-in. |
A special address (you+tag@…) is a different test user with the same password. Apps that strip +tags from emails will merge them into one user. | Breaks special addresses in such apps. |