Create an App ID

1. Go to Certificates, Identifiers & Profiles.
2. Select Identifiers in the sidebar, make sure App IDs is selected in the dropdown on the right, and click the + button.
3. On the Register a New Identifier page, keep App IDs selected and click Continue.
4. With App selected, click Continue.
5. Fill in Description, and set Bundle ID to Explicit with your app's identifier — e.g. com.yourcompany.yourapp. It must match the ios.bundleIdentifier in your app.json.
6. Scroll to Capabilities and check Sign In with Apple.
7. Click Continue, then Register.

Create a Services ID

1. Back on Certificates, Identifiers & Profiles, switch the dropdown to Services IDs and click +.
2. Keep Services IDs selected and click Continue.
3. Fill in Description and Identifier — e.g. com.yourcompany.yourapp.service. This identifier is what you will set as AUTH_APPLE_ID, so it must be different from the App ID above.
4. Click Continue, then Register.

Create a signing key

1. Click Keys in the sidebar, then +.
2. Give the key a name.
3. Check Sign In with Apple and click Configure beside it.
4. Select the App ID you created as the Primary App ID, and click Save.
5. Click Continue, then Register.
6. Download the .p8 file.
7. Note the Key ID shown next to it, and your Team ID from the top right of the developer portal.

Find your Convex HTTP Actions URL

In the Convex dashboard, open Settings → URL & Deploy Key and copy the HTTP Actions URL. It ends in .site, not .cloud — the .cloud URL is what your app talks to for queries and mutations, and it is not what Apple redirects to.

Configure the Services ID for web authentication

1. Return to Identifiers, switch the dropdown to Services IDs, and click the Services ID you created.

2. Make sure Sign In with Apple is checked and click Configure.

3. Set the Primary App ID to your App ID.

4. In Domains and Subdomains, enter just the domain portion of your HTTP Actions URL — no scheme, no path:

   fast-horse-123.convex.site
   

5. In Return URLs, enter the full callback URL:

   https://fast-horse-123.convex.site/api/auth/callback/apple
   

6. Click Next, confirm the values, and click Done.

7. Back on the Services ID page, click Continue, then Save.

Generate the JWT client secret

Apple does not issue a static secret. You sign one yourself with the .p8 key, using four pieces of information:

Copyconst jwt = require('jsonwebtoken');
const fs = require('fs');
 
const privateKey = fs.readFileSync('AuthKey_XXXXXXXXXX.p8');
 
const token = jwt.sign(
  {
    iss: 'YOUR_TEAM_ID',
    iat: Math.floor(Date.now() / 1000),
    exp: Math.floor(Date.now() / 1000) + 15777000, // 6 months
    aud: 'https://appleid.apple.com',
    sub: 'YOUR_SERVICE_ID',
  },
  privateKey,
  { algorithm: 'ES256', header: { kid: 'YOUR_KEY_ID' } }
);
 
console.log(token);

Sign it locally. The .p8 is a private key: pasting it into an online JWT generator hands whoever runs that page the ability to authenticate as your app.

Set the environment variables

pnpmnpmyarnbun
pnpm dlx convex env set AUTH_APPLE_ID your_service_id
npx convex env set AUTH_APPLE_SECRET your_generated_jwt
Copy

Or add them in the Convex dashboard under Settings → Environment Variables. Set them on your production deployment too, with --prod.