Facebook

Implemented flow

The mock implements classic Facebook Login's web authorization code flow: authorization, code exchange, /me profile lookup, debug_token inspection and permission revocation.

It does not issue ID tokens, including when openid is requested. Limited Login, implicit login, long-lived token exchange and app access tokens are not implemented. Graph API support is limited to the endpoints used for sign-in; other profile fields and broader Graph features are not served.

Sources: manual web login flow, Limited Login, long-lived tokens.

Using the connector

// Better Auth: pass the same options you give socialProviders.facebookimport { mockFacebook } from "@mockatoo/connect-better-auth";const facebook = { clientId: process.env.FACEBOOK_CLIENT_ID!,                   clientSecret: process.env.FACEBOOK_CLIENT_SECRET! };export const auth = betterAuth({  socialProviders: process.env.NODE_ENV === "production" ? { facebook } : {},  plugins: process.env.NODE_ENV === "production" ? [] : [mockFacebook(facebook)],});// Auth.jsimport Facebook from "next-auth/providers/facebook";import { MockFacebook } from "@mockatoo/connect-authjs";providers: [process.env.NODE_ENV === "production" ? Facebook() : MockFacebook()],
  • No refresh token is issued. Token exchange for long-lived access is also unavailable, so test that path separately against Facebook.
  • /me supplies ID, name, email and picture. It has no email_verified, so neither connector marks email verified. +noemail exercises a user declining the email permission.
  • Known permissions are granted without App Review, but granting them does not add unsupported fields or API features. This cannot validate your app approval.
  • Photos use mock URLs, while real Facebook photo URLs expire. Use you+nophoto@example.com to test a user whose picture is a silhouette (is_silhouette: true).
  • Facebook's callback includes the #_=_ fragment. The mock preserves it.

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
nophotoNo profile photo. LinkedIn omits picture from the ID token and userinfo; Facebook returns a silhouette with is_silhouette: trueExample
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 www.facebook.com and graph.facebook.com, so mockFacebook() contains a copy of Better Auth's debug_token check and /me lookup with the URLs changed, and its token URL with Better Auth's Graph API version (v24.0).Hides changes in a newer Better Auth until the copy is updated.
An unknown permission always stops at Facebook's page "Invalid Scope: emial (Please check lower letter case or delimiter)", as it does for the app's admin. Older reports say Facebook shows such a page only to the app's developers and testers, and drops the unknown permission for everyone else.Breaks sign-in with a misspelled or retired permission that a live app's users get through (without that permission).
Every known permission the app asks for is granted, as for the app's developers, and the user declines none, except that a +noemail user declines email. But the mock only has a user's id, name, email and picture: other User fields (birthday, gender, friends, …) are left out of /me, as if not granted. Real Facebook grants permissions beyond public_profile and email to other users only after App Review, and users can decline email.Hides a missing App Review and a user who declines a permission; breaks features that read other User fields.
Profile photos are served by the mock as SVGs. At Facebook, picture.data.url is a signed scontent…fbcdn.net URL that expires (its oe parameter). Use +nophoto for a silhouette (is_silhouette: true).Hides apps that store an expiring photo URL.
No ID token is ever issued. Facebook returns one from the classic code flow once the user has granted openid (RS256, iss https://www.facebook.com/ or, once, without the slash, a 90-day exp, nonce, at_hash, name, given_name, family_name, picture), and then on every later sign-in, even ones that don't ask for openid (with an empty nonce). Limited Login (iOS), its discovery and its keys at limited.facebook.com aren't served either.Breaks apps that read Facebook's ID token. Hides an app that receives one it didn't ask for: Better Auth then takes the profile from the ID token instead of /me.
Only the authorization code grant is modeled. response_type=token, long-lived token exchange (grant_type=fb_exchange_token) and app access tokens (client_credentials) are refused.Breaks apps that exchange tokens or call the Graph API as the app.
appsecret_proof is ignored. An app with "Require App Secret" turned on gets an error from Facebook for every Graph call without a correct proof.Hides a missing or wrong appsecret_proof.

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.