Apple Sign-In JS Bridge
The Apple Sign-In bridge lets your website open the native Sign in with Apple sheet in your iOS app and receive the signed-in user's details and an identity token back. Your backend verifies that token to log the user in.
This bridge is for iOS only. The app does not take over your website's Apple login automatically — inside the iOS app, your "Sign in with Apple" button must trigger this bridge.
For a general introduction to the JavaScript Bridge, see the Overview article.
Prerequisites
Before the bridge can trigger Apple Sign-In:
- Go to your iOS app's Integration Modules and enable Apple Sign-In.
- Enable Sign In with Apple for your app's identifier in your Apple Developer account, then create a new provisioning profile on the iOS Code Signing page.
- Rebuild your app so the new settings are included.
See the Apple Sign-In article for step-by-step setup.
How It Works
- The user taps your website's "Sign in with Apple" button inside the iOS app.
- Your website sends an
apple_sign_inmessage to the app via the bridge. - The app opens the native Sign in with Apple sheet and the user confirms.
- The app sends the user's details and identity token back to your website.
- Your website sends the identity token to its backend, which verifies it and logs the user in.
Triggering Sign-In
appilix.postMessage(JSON.stringify({
type: "apple_sign_in",
props: {
nonce: "RANDOM_STRING_FROM_YOUR_SERVER"
}
}));props is optional — { type: "apple_sign_in" } on its own is a valid request.
Parameters
| Parameter | Required | Description |
|---|---|---|
nonce | No | A random string your backend generated for this sign-in. The app sends its SHA-256 hash to Apple, binding the identity token to it. If omitted, the app generates one |
Scopes always come from the Apple Sign-In module settings and cannot be set from the bridge. They default to email name when the Scopes field is empty.
Handling the Response
Set up the listener before triggering sign-in:
appilix.onmessage = function(event) {
const data = JSON.parse(event.data);
if (!data || data.type !== "apple_sign_in") return;
if (!data.response.error) {
const { identity_token, nonce, given_name, family_name } = data.response;
// Send the token to your backend to verify it and log the user in.
// Include the name — Apple only returns it on the first sign-in.
fetch("/auth/apple/app", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ identity_token, nonce, given_name, family_name })
});
} else {
// Sign-in failed or was cancelled
console.log("Sign-in failed:", data.response.error);
}
appilix.onmessage = null;
};Response Fields
| Field | Description |
|---|---|
error | null on success, otherwise the reason sign-in failed (e.g. the user closed the sheet) |
user_id | Stable Apple user ID — the same value as the sub claim in the identity token |
email | User's email address. May be a private relay address (@privaterelay.appleid.com) if the user chose Hide My Email. Empty if email is not in the module's Scopes |
name | User's full name. Only returned on the first sign-in to your app, empty afterwards |
given_name | User's first name. Only returned on the first sign-in to your app, empty afterwards |
family_name | User's last name. Only returned on the first sign-in to your app, empty afterwards |
identity_token | Signed Apple identity token (JWT) issued for your app's Bundle ID. Always present on success |
code | Short-lived authorization code your backend can exchange with Apple for tokens |
nonce | The raw nonce used for this sign-in — the one you passed, or the one the app generated |
On failure, every field except error is null, so the response always has the same shape.
Verifying the Identity Token on Your Backend
The email, name, and other fields are returned for convenience — they are not proof of identity on their own. Before logging the user in, your backend must verify identity_token and check that:
- The token's signature is valid against Apple's public keys at
https://appleid.apple.com/auth/keys. issishttps://appleid.apple.com.audequals your app's Bundle ID — not a Services ID, because the native sign-in is issued to the app.exphas not passed.nonceequals the SHA-256 hash (lowercase hex) of the raw nonce.
Node.js (jose):
const { createRemoteJWKSet, jwtVerify } = require("jose");
const crypto = require("crypto");
const BUNDLE_ID = "com.example.app";
const APPLE_KEYS = createRemoteJWKSet(new URL("https://appleid.apple.com/auth/keys"));
async function verifyAppleIdentityToken(identityToken, rawNonce) {
const { payload } = await jwtVerify(identityToken, APPLE_KEYS, {
issuer: "https://appleid.apple.com",
audience: BUNDLE_ID
});
const hashedNonce = crypto.createHash("sha256").update(rawNonce).digest("hex");
if (payload.nonce !== hashedNonce) throw new Error("Nonce mismatch");
return { apple_id: payload.sub, email: payload.email };
}PHP (firebase/php-jwt):
use Firebase\JWT\JWT;
use Firebase\JWT\JWK;
$bundle_id = 'com.example.app';
$keys = json_decode(file_get_contents('https://appleid.apple.com/auth/keys'), true);
try {
$claims = (array) JWT::decode($identity_token, JWK::parseKeySet($keys));
} catch (\Exception $e) {
$claims = null; // Invalid or expired token — do not log the user in
}
if ($claims
&& $claims['iss'] === 'https://appleid.apple.com'
&& $claims['aud'] === $bundle_id
&& ($claims['nonce'] ?? '') === hash('sha256', $raw_nonce)) {
$apple_id = $claims['sub'];
$email = $claims['email'] ?? '';
}Identify the user by sub (the same value as user_id) rather than by email — it never changes, while the email can be a relay address or be changed by the user.
Using Your Own Nonce
For the strongest protection, generate the nonce on your backend, store it in the user's session, and pass it in props. Your backend then compares the token's nonce claim with the hash of the stored value, rather than the value sent back by the page. This prevents a captured identity token from being reused in another session.
Exchanging the Authorization Code
Only needed if your backend calls Apple's APIs for the user — for example, to revoke their tokens when they delete their account.
From your backend, send a POST request to https://appleid.apple.com/auth/token with:
| Parameter | Value |
|---|---|
code | The code from the response |
client_id | Your app's Bundle ID |
client_secret | A JWT you sign with your Sign in with Apple private key (see below) |
grant_type | authorization_code |
The client_secret is a JWT signed with ES256 using a private key (.p8) created under Certificates, Identifiers & Profiles → Keys with Sign In with Apple enabled:
- Header:
kidis the Key ID iss: your Apple Developer Team IDsub: your app's Bundle IDaud:https://appleid.apple.comiat/exp: issue and expiry time — at most 6 months apart
Apple responds with an access token and a refresh token. Store the refresh token if you need to revoke access later. Authorization codes are single-use and expire after 5 minutes, so exchange them as soon as your backend receives them.
Revoking Tokens When a User Deletes Their Account
Apple requires apps that let users create accounts to let them delete those accounts in the app. For users who signed in with Apple, send a POST request to https://appleid.apple.com/auth/revoke with client_id (your Bundle ID), client_secret, token (the stored refresh token), and token_type_hint set to refresh_token.
Complete Example
function signInWithApple() {
// Apple Sign-In is available only inside the iOS app
const isIOSApp = typeof appilix !== 'undefined' &&
/iPhone|iPad|iPod|Macintosh/.test(navigator.userAgent);
if (!isIOSApp) {
startWebAppleLogin();
return;
}
appilix.onmessage = function(event) {
const data = JSON.parse(event.data);
if (!data || data.type !== "apple_sign_in") return;
appilix.onmessage = null;
if (data.response.error) {
console.error("Sign-in error:", data.response.error);
return;
}
const { identity_token, nonce, given_name, family_name } = data.response;
// Send the token to your backend for verification
fetch("/auth/apple/app", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ identity_token, nonce, given_name, family_name })
})
.then(res => res.json())
.then(result => {
if (result.success) window.location.href = "/dashboard";
});
};
appilix.postMessage(JSON.stringify({
type: "apple_sign_in"
}));
}startWebAppleLogin() stands for whatever your website already does in a browser — or hide the button there. Macintosh is included because iPads report a desktop user agent. If you set a Custom User Agent in App Settings, adjust this check to match it.
Important Notes
- This bridge is for iOS only. In Android apps, show your Apple button only if your website has its own web Apple login.
- Always verify
identity_tokenon your backend. Never log a user in based on the client-side response alone. - Save the user's name on the first sign-in — Apple does not send it again.
- If the user closes the sign-in sheet,
erroris set and no token is returned. - Implementing this requires changing your website's sign-in button logic and adding a backend endpoint that verifies the token. Involve a developer if needed.