POST
Sign in with Apple

Overview

Signs a user in (or registers them on first use) with Sign in with Apple. The mobile app performs the native Apple authorization, exchanges the resulting Apple identity token for a Firebase credential, and POSTs the Firebase ID token here — the same request body and response shape as /oauth/google. The backend verifies the token with firebase-admin (signature, expiry, issuer, audience = our Firebase project) and additionally checks that the token’s firebase.sign_in_provider claim is apple.com. That pin matters: both providers mint Firebase ID tokens for the same project, so the signature check alone cannot tell them apart, and without it a Google token POSTed here would create an APPLE-bound account. There are three outcomes:
  • First-time Apple user → a new account is created with oauthProvider: 'APPLE'. The response is 201 Created with isNewUser: true. The client should route the user into onboarding.
  • Returning Apple user (same Apple identity) → 200 OK with isNewUser: false.
  • Email already owned by a non-Apple account → 409 ACCOUNT_EXISTS_VIA_OAUTH. Swappr does not silently attach Apple to a pre-existing email/password (or Google) account.
Private-relay emails. When the user chooses Hide My Email, Apple supplies a @privaterelay.appleid.com address instead of their real one. It is a real, deliverable address and is stored and treated exactly like any other — nothing downstream special-cases it. Note that the relay address is per-app, so the same person signing in with Google will have a different email and therefore a separate account.
Name is only ever sent once. Apple returns the user’s full name on the first authorization only, never on subsequent sign-ins. Swappr does not depend on it: OAuth accounts start with firstName / lastName as null and collect the name during onboarding, exactly as Google accounts do.

Authentication

None required. The Firebase ID token in the body is the credential.

Path parameters

None.

Query parameters

None.

Request body

Example payload

Response — 201 Created (new user) / 200 OK (returning user)

Example response — 201

Error responses

Example error — 401

Side effects

  • First-time sign-in only: inserts a new row into the users collection with oauthProvider: 'APPLE', oauthId set to the Firebase uid, passwordHash: null, and emailVerified taken from the token.
  • Issues a new session: inserts a refresh_tokens row and signs an access JWT.
  • No email is sent (Apple has already verified the address).

Rate limiting

This endpoint shares the auth burst limiter (10 requests / minute / IP) with /login, on top of the router-level /auth/* cap.

Notes for the client

  1. The iOS app must have the Sign in with Apple capability on its App ID and the com.apple.developer.applesignin entitlement.
  2. Generate a random nonce, pass its SHA-256 hash to Apple, and hand the raw nonce to Firebase alongside the identity token. This binds the token to that one sign-in attempt so it cannot be replayed.
  3. Read the Firebase ID token (user.getIdToken()), not the Apple identity token, and POST it here.
  4. The button is iOS-only: Apple only requires it on Apple platforms, and the Android path would need a separate Services ID that Swappr does not configure.

See also

curl