Apple

Implemented flow

The mock implements the Sign in with Apple web authorization code flow: authorize, return the code to your callback, exchange it for an access token, refresh token and signed ID token, then refresh or revoke tokens. It publishes discovery and signing keys. Apple has no userinfo endpoint in this flow.

Other Apple services and native Apple SDK interactions are not implemented. The connector uses shared mock credentials in place of Apple's signed client secret; successful mock sign-in cannot validate your Apple key or Services ID.

Sources: Sign in with Apple REST API, authorization response.

OpenID Connect (OIDC)

This provider supports OpenID Connect (OIDC), which adds signed ID tokens to OAuth 2.0 so your app can verify the signed-in user's identity. Mockatoo publishes OIDC discovery and signing keys for this provider. See the Hono + oauth4webapi example for a minimal authorization code flow with discovery and ID-token validation, including this provider's differences, without an auth abstraction.

Using the connector

// Better Auth: pass the same options you give socialProviders.appleimport { mockApple } from "@mockatoo/connect-better-auth";const apple = { clientId: process.env.APPLE_CLIENT_ID!,                clientSecret: process.env.APPLE_CLIENT_SECRET! };export const auth = betterAuth({  socialProviders: process.env.NODE_ENV === "production" ? { apple } : {},  plugins: process.env.NODE_ENV === "production" ? [] : [mockApple(apple)],});// Auth.jsimport Apple from "next-auth/providers/apple";import { MockApple } from "@mockatoo/connect-authjs";providers: [process.env.NODE_ENV === "production" ? Apple() : MockApple()],
  • With name or email scope, the callback uses form POST. Ensure your callback and state handling accept it.
  • The name arrives in the separate user field, never in the ID token. Store it on first sign-in; +returning omits that field to exercise later sign-ins.
  • Handle private relay addresses and boolean claims encoded as strings; use +hidden and +strings to exercise these cases.
  • Refreshing does not return a replacement refresh token. Revocation is implemented for testing account deletion flows.
  • Better Auth's connector adds the mock origin to trusted origins for local form callbacks. The mock accepts HTTP and localhost callbacks; real Apple requires an eligible HTTPS callback.

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
hiddenHide My Email: a @privaterelay.appleid.com address with is_private_email: trueExample
stringsemail_verified and is_private_email are the strings "true"/"false" instead of booleansExample
returningSame user and email as without the tag, signing in again. Google: no refresh token unless prompt=consent. Apple: no user field, so no nameExample
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
mockApple() adds the mock's origin to Better Auth's trusted origins. A mock on localhost is the same site as a local app, so Apple's form POST carries the app's cookies and Better Auth would otherwise reject it. Real Apple is cross-site, so Better Auth never checks its origin.Better Auth trusts one extra origin while you use the mock.

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.