X

Implemented flow

The mock implements the OAuth 2.0 authorization code flow with PKCE for a confidential X Web App: authorization, code exchange, /2/users/me, refresh and revocation. Both S256 and plain PKCE are supported; PKCE and state are required.

OAuth 1.0a, public Native/SPA clients, app-only authentication and OIDC are not implemented. Posts, timelines and other X APIs are not served.

Sources: OAuth 2.0 authorization code flow, current user lookup.

Using the connector

// Better Auth: pass the same options you give socialProviders.twitterimport { mockTwitter } from "@mockatoo/connect-better-auth";const twitter = { clientId: process.env.TWITTER_CLIENT_ID!,                  clientSecret: process.env.TWITTER_CLIENT_SECRET! };export const auth = betterAuth({  socialProviders: process.env.NODE_ENV === "production" ? { twitter } : {},  plugins: process.env.NODE_ENV === "production" ? [] : [mockTwitter(twitter)],});// Auth.jsimport Twitter from "next-auth/providers/twitter";import { MockTwitter } from "@mockatoo/connect-authjs";providers: [process.env.NODE_ENV === "production" ? Twitter() : MockTwitter()],
  • Both tweet.read and users.read are needed for /2/users/me. Email also needs users.email and the confirmed_email field. Auth.js does not request it by default; Better Auth substitutes a placeholder if it is absent.
  • A new sign-in invalidates the user's earlier tokens. Because the mock has a shared client, this affects other apps using the same mock and test identity.
  • Request offline.access for refresh tokens. Refresh tokens work once, and refreshing invalidates the old access token. Store the replacement token.
  • Codes expire after 30 seconds. Send client credentials with Basic auth when redeeming codes, refreshing or revoking tokens.
  • Every profile uses the default avatar and synthetic metrics. Rate limits and billing are not simulated.

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.

TagBehavior
unverifiedemail_verified: false (GitHub: primary email verified: false; Discord: verified: false; LinkedIn: "false" in the ID token)Example
renamedSame user ID (sub, Microsoft oid, GitHub, Discord, X and Facebook id) as the address without +renamed, different emailExample
nonameNo name (Google: also no given_name/family_name; GitHub: name: null; Discord: global_name: null)Example
noemailNo 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
revokedSign-in works; every refresh returns invalid_grant (GitHub: bad_refresh_token, and only with offline_access; X: invalid_request)Example
badcodeThe code exchange fails (invalid_grant; GitHub: bad_verification_code; LinkedIn and X: invalid_request; Facebook: Invalid verification code format.)Example
downThe token endpoint returns 503Example
flakyThe first exchange of each code returns 503; a retry succeedsExample
slowToken responses are delayed (10 seconds)Example

Known differences

This provider

DifferenceEffect
Better Auth hardcodes x.com and api.x.com, so mockTwitter() contains a copy of Better Auth's two /2/users/me lookups (the profile, then confirmed_email) with the URLs changed.Hides changes in a newer Better Auth until the copy is updated.
The shared client is a confidential client (an X Web App), so the token and revoke endpoints require its credentials in a Basic header. Public clients (Native App or Single Page App), which send only client_id in the body, aren't modeled.Breaks an app registered with X as a public client.
As at X, exchanging a new code ends the user's earlier access and refresh tokens. X does this per app; every app shares the mock's one client, so a sign-in to any app ends the user's X tokens in every other app using the same mock.Breaks tests that run two apps against one mock as the same test user and then use the first app's tokens.
Every user has X's default avatar (abs.twimg.com/sticky/default_profile_images/default_profile_normal.png). Real users mostly have their own pbs.twimg.com/profile_images/…_normal.jpg, which apps often rewrite to a larger size by dropping _normal.Hides problems in custom avatar URLs and their size variants.
/2/users/me fills in id, name, username, created_at, description, profile_image_url, protected, verified, confirmed_email and public_metrics (all zero, like a new account). It accepts X's other user.fields (verified_type, entities, pinned_tweet_id, …) but leaves them out, and ignores expansions and tweet.fields.Breaks app features that read verification type, pinned posts or real follower counts.
Nothing is rate limited or billed, and there are no x-rate-limit-* headers. X allows a user 75 /2/users/me requests per 15 minutes (429 after that), and its pay-per-use plans charge per request.Hides missing retry handling and sign-ins that fail once an app's quota runs out.

Shared mock limits

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