# 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](https://discord.com/developers/docs/topics/oauth2).

## Using the connector

```ts
// Better Auth: pass the same options you give socialProviders.discord
import { 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 sends
import 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 `identify` for a profile and `email` for email and verification status. A Discord account registered with a phone number has `email: null` and `verified: false` even with the `email` scope; use `you+noemail@example.com` to test this. Better Auth rejects the account with `email_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=none` permits 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](../email-tags.md).

| Tag | Behavior | |
| --- | --- | --- |
| `unverified` | `email_verified: false` (GitHub: primary email `verified: false`; Discord: `verified: false`; LinkedIn: `"false"` in the ID token) | [Example](https://github.com/mockatoo/examples/blob/main/better-auth-next/tests/tags/unverified.spec.ts) |
| `renamed` | Same user ID (`sub`, Microsoft `oid`, GitHub, Discord, X and Facebook `id`) as the address without `+renamed`, different email | [Example](https://github.com/mockatoo/examples/blob/main/better-auth-next/tests/tags/renamed.spec.ts) |
| `noname` | No name (Google: also no `given_name`/`family_name`; GitHub: `name: null`; Discord: `global_name: null`) | [Example](https://github.com/mockatoo/examples/blob/main/better-auth-next/tests/tags/noname.spec.ts) |
| `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](https://github.com/mockatoo/examples/blob/main/better-auth-next/tests/tags/noemail.spec.ts) |
| `revoked` | Sign-in works; every refresh returns `invalid_grant` (GitHub: `bad_refresh_token`, and only with `offline_access`; X: `invalid_request`) | [Example](https://github.com/mockatoo/examples/blob/main/better-auth-next/tests/tags/revoked.spec.ts) |
| `badcode` | The code exchange fails (`invalid_grant`; GitHub: `bad_verification_code`; LinkedIn and X: `invalid_request`; Facebook: `Invalid verification code format.`) | [Example](https://github.com/mockatoo/examples/blob/main/better-auth-next/tests/tags/badcode.spec.ts) |
| `down` | The token endpoint returns 503 | [Example](https://github.com/mockatoo/examples/blob/main/better-auth-next/tests/tags/down.spec.ts) |
| `flaky` | The first exchange of each code returns 503; a retry succeeds | [Example](https://github.com/mockatoo/examples/blob/main/better-auth-next/tests/tags/flaky.spec.ts) |
| `slow` | Token responses are delayed (10 seconds) | [Example](https://github.com/mockatoo/examples/blob/main/better-auth-next/tests/tags/slow.spec.ts) |

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