Apple OAuth

This page details how to add and configure Apple OAuth for Authverse projects.

Install the Apple Provider

Execute the following command to add the Apple provider to your project:

npx authverse@latest oauth apple

The command installs jose, adds the Apple provider to your socialProviders, and adds https://appleid.apple.com to trustedOrigins in auth.ts.

Configure Apple Developer Portal

To support Apple Sign-In, you need to configure your app in the Apple Developer Portal. Apple Sign In requires an active Apple Developer account.

1. App ID: Create an App ID for your application with the Sign In with Apple capability enabled.
2. Service ID: Create a Service ID for your web application.
   • The Service ID Identifier will be your Client ID (APPLE_CLIENT_ID).
   • Enable Sign In with Apple on the Service ID.
   • Under Primary App ID, select the App ID created above.
   • Under Domains and Subdomains, list the root domains used for Sign In with Apple.
   • Under Return URLs, enter the exact callback URL: https://yourdomain.com/api/auth/callback/apple
3. Private Key: Create a Sign-In with Apple Private Key (.p8 file) and note the Key ID and your Team ID.

[!WARNING] Apple does not support localhost or non-HTTPS return URLs. During development you must use a domain with a valid HTTPS/TLS certificate. The Return URL must exactly match the callback URL used by your deployment.

[!IMPORTANT] Apple emits the email claim only on the first authorization. Subsequent sign-ins omit it. Authverse relies on Better Auth's account model (keyed by Apple's stable provider identity), so repeat sign-ins do not create duplicate users or fail because of a missing email.

Environment Setup

Add the following variables to your project's .env file:

APPLE_CLIENT_ID=
APPLE_TEAM_ID=
APPLE_KEY_ID=
APPLE_PRIVATE_KEY=
APPLE_BUNDLE_ID=

• APPLE_CLIENT_ID: Your Service ID identifier.
• APPLE_TEAM_ID: Your Apple Developer Team ID.
• APPLE_KEY_ID: The Key ID of your Sign In with Apple private key.
• APPLE_PRIVATE_KEY: The contents of your .p8 key file. When stored in an environment variable, escaped \n newlines are handled automatically.
• APPLE_BUNDLE_ID: Optional. Required for native iOS (uses the app's bundle ID instead of the service ID).

The clientSecret JWT is generated automatically for you in auth.ts from these values using the jose package. You do not need to generate or commit a static client secret.

Import and Use the Apple Provider Component

Import the prebuilt provider component and integrate it into your UI:

import { AppleOAuthButton } from "@/components/authverse/AppleOAuthButton";

<AppleOAuthButton />;

This component renders the Apple sign-in button at its location.

Notes & Troubleshooting

• Return URLs: Ensure the Return URL in the Apple Developer Portal exactly matches https://yourdomain.com/api/auth/callback/apple. Localhost is not supported by Apple.
• Trusted Origins: Apple requires https://appleid.apple.com to be in your trusted origins list. The CLI adds it without removing any user-defined origins.
• Bundle ID: For cross-platform applications, ensure APPLE_BUNDLE_ID is set to your native app's bundle identifier.
• Client Secret: The JWT client secret expires within six months and is regenerated dynamically by the generated generateAppleClientSecret() function — no manual rotation needed.