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.readandusers.readare needed for/2/users/me. Email also needsusers.emailand theconfirmed_emailfield. 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.accessfor 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.
| 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 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
| 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. |