# 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](https://docs.x.com/fundamentals/authentication/oauth-2-0/authorization-code),
[current user lookup](https://docs.x.com/x-api/users/get-me).

## Using the connector

```ts
// Better Auth: pass the same options you give socialProviders.twitter
import { 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.js
import 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](../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 `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. |
