> ## Documentation Index
> Fetch the complete documentation index at: https://docs.launchtoday.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Apple Sign-In Setup

> Complete guide to configuring Apple Sign-In for iOS apps

## Overview

Apple Sign-In provides a secure and privacy-focused authentication method for iOS users. The Launch boilerplate already includes the Apple Sign-In wiring on both the API and the mobile client—you just need to enable it and add your credentials.

## Prerequisites

* **Apple Developer Account** (paid membership required)
* **iOS App** with unique Bundle Identifier
* **Access to Apple Developer Console**

<Tip>
  Start with [Backend Authentication Setup](/authentication/backend-setup) so
  your API and env file are in place.
</Tip>

## Steps

## Step 0: Set Up ngrok (Recommended First)

Apple and Google sign-in flows work best with a stable HTTPS callback URL. Use
ngrok to expose your local API, then set that URL in both the backend and mobile
env files.

Run ngrok and copy the HTTPS forwarding URL:

```bash theme={null}
ngrok http 3001
```

Example forwarding URL:

```
https://27f9fd215cd7.ngrok-free.app
```

1. Start a tunnel to your API (running on port 3001).
2. Copy the HTTPS URL from ngrok.
3. Update `apps/api/.env` with `BETTER_AUTH_URL` set to the ngrok URL.
4. Update `apps/mobile/.env` with `EXPO_PUBLIC_API_URL` set to the same ngrok URL.
5. Restart the API and the mobile app so the new URLs are used.

## Step 1: Create or Configure Your App ID

1. Log in to [Apple Developer Console](https://developer.apple.com)
2. Select **Account** from the top navigation
3. Choose **Certificates**
4. Pick your App ID (or create one) and set a bundle identifier such as
   `com.company.example`
5. Scroll down, find **Sign in with Apple**, enable it, and make sure
   **Enable as a primary App ID** is checked
6. Click **Save**

## Step 2: Generate a Private Key

1. Select **Account** from the top navigation
2. Open **Keys**
3. Click the **+** button
4. Enter a **Key Name** (e.g., "Launch Apple Sign-In")
5. Find **Sign in with Apple** and click **Configure**
6. Choose your **Primary App ID** (this should be the same bundle ID you set in Step 1, part 4)
7. Click **Save**
8. Click **Continue**, then **Register**
9. Download the `.p8` key immediately (you can only download it once)
10. Note the **Key ID** and your **Team ID** for the next steps

<Warning>
  The `.p8` file can only be downloaded once. Store it securely and never commit it to version control.
</Warning>

## Step 3: Convert the Private Key to Base64

Apple requires the `.p8` file to be stored as a single-line base64 string in your
environment. Convert the key locally using a secure method you trust, and avoid
online converters.

Example command:

```
base64 -i AuthKey_KEYID.p8 | tr -d '\n'
```

## Step 4: Update Your API Environment

Add the values below to your backend environment file (see
`apps/api/.env` for where they live). The backend reads these at startup to
enable Apple Sign-In.

After updating the API environment, restart the API server so the new values
are loaded. Then restart the mobile app by running `pnpm prebuild`, followed by
`pnpm ios` to launch the iOS app.

You will need the following values:

* `APPLE_CLIENT_ID` (your iOS bundle identifier)
* `APPLE_TEAM_ID` (your 10-character team ID)
* `APPLE_KEY_ID` (your 10-character key ID)
* `APPLE_PRIVATE_KEY_BASE64` (the base64 version of the `.p8` key)

### Finding Your Team ID

1. Go to [Apple Developer Console](https://developer.apple.com)
2. Click on your name in the top right
3. Your **Team ID** is displayed next to your name

### Finding Your Bundle Identifier

1. In Apple Developer Console, go to **Identifiers** → **App IDs**
2. Select your app
3. The **Identifier** field shows your Bundle ID

## Step 5: Mobile App Configuration

Update `apps/mobile/app.config.ts` to:

* Set your iOS bundle identifier (this must match `APPLE_CLIENT_ID`).
* Uncomment the `expo-apple-authentication` plugin.
* Enable the Apple Sign-In entitlement when you are ready to ship.

## Step 6: Backend Configuration

The boilerplate already includes the server-side Apple Sign-In wiring in
`apps/api/src/services/auth.ts`. Once the Apple environment values exist, the
provider is enabled automatically.

## Step 7: Testing

Confirm Apple Sign-In is working by:

1. Running the iOS app on a simulator or device.
2. Tapping the Apple Sign-In button on the login screen.
3. Verifying that you return to the app authenticated.

### Success Checks

* You can sign in successfully from the app using Apple.
* Query your database and confirm a new user appears in the `users` table and
  a linked record exists in the `accounts` table.

## Troubleshooting

* **Apple Sign-In button not appearing**: ensure you are running on iOS and that
  `expo-apple-authentication` is enabled in `apps/mobile/app.config.ts`.

* **Invalid client**: confirm your bundle ID matches `APPLE_CLIENT_ID`.

* **Backend validation errors**: verify all Apple env values are set and restart
  the API after changes.