> For the complete documentation index, see [llms.txt](https://docs.buildnatively.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.buildnatively.com/natively-platform/features/social-auth/sign-in-with-apple.md).

# Sign In with Apple

## What is Sign In with Apple?

Sign In with Apple lets your users authenticate using their Apple ID with a single tap, using Face ID or Touch ID to confirm. It's a fast, privacy-friendly login option that doesn't require users to create a new account or remember a password. Because Apple can hide users' real email addresses behind a private relay, users often trust it more than other login options.

{% hint style="info" %}
Sign In with Apple feature uses a native iOS component - no [Social Auth](/natively-platform/features/social-auth.md) or [Deep Links](/natively-platform/features/deep-links.md) required. 

However, if your app uses the Social Auth feature to offer any other third-party login (Google, Facebook, etc.), Apple requires you to also include Sign In with Apple, and those OAuth providers will require Social Auth and Deep Links. 
{% endhint %}

{% hint style="warning" %}
Sign In with Apple is only available on iOS. It should not appear or function on Android devices or in a web browser.
{% endhint %}

## Prerequisites

{% hint style="success" %}
This feature requires the **Unlimited** or **Lifetime** plan. [See all plans](/getting-started/subscription-plans.md)
{% endhint %}

* An [Apple Developer](https://developer.apple.com/account) account.
* Your iOS app is already [published](/natively-platform/app-info/ios-build.md) in the Natively Dashboard.

## App Capabilities Configuration

{% hint style="info" %}
App capabilities define what system-level features your app is allowed to use on iOS. Before Natively can include the Sign In with Apple feature in your build, the **Sign In with Apple** capability must be explicitly enabled in your Apple Developer account for your app's Bundle ID.
{% endhint %}

* Open your [Apple Developer account](https://developer.apple.com/account) and navigate to [Certificates, IDs & Profiles > Identifiers](https://developer.apple.com/account/resources/identifiers/list).
* Select your app's Bundle ID.
* Scroll down the **Capabilities** list and enable **Sign In with Apple**.
* Click **Save** and confirm.

## Natively Dashboard Setup

Before proceeding, make sure you have completed the [App Capabilities Configuration](#app-capabilities-configuration) step above.

* Open your Natively app dashboard and navigate to **Features** > **Social Auth** > **Sign In with Apple (iOS only)**.
* Toggle the feature to **Enabled**.
* Click **Save**.
* Rebuild your iOS app.

{% hint style="warning" %}
You must rebuild your app for these changes to take effect.
{% endhint %}

## Implementation

Choose your integration method below: **Bubble.io Plugin** (No-Code), **JavaScript SDK** (Code), or **AI Agents** (for AI-powered editors like Lovable, Base44, and Replit).

### Initialization

{% tabs %}
{% tab title="Bubble.io Plugin" %}
**Check Plugin**

Before starting, verify if the Natively plugin is already installed in your Bubble project.

1. Open your Bubble editor and navigate to the Plugins tab in the left sidebar.
2. **Check Installed Plugins:** Look through your list of installed plugins for "Natively iOS & Android app builder".
   * If it IS installed: Check the version number. If an update is available (e.g., you see a button saying "Update"), click it to ensure you have the latest features and bug fixes.

<figure><img src="https://docs.buildnatively.com/~gitbook/image?url=https%3A%2F%2F3352617162-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F90tV7pYflEQdiAr2VfWu%252Fuploads%252FmfnSUug82IdnxOAoBrak%252Fnatively_app_builder_bubble_plugin_update.png%3Falt%3Dmedia%26token%3Dc193f69f-b03b-4be4-b80b-f34ba37ac212&#x26;width=768&#x26;dpr=3&#x26;quality=100&#x26;sign=a89e4510&#x26;sv=2" alt=""><figcaption></figcaption></figure>

* If it is NOT installed: Click the + Add plugins button, search for "Natively", and click Install.

<figure><img src="https://docs.buildnatively.com/~gitbook/image?url=https%3A%2F%2F3352617162-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F90tV7pYflEQdiAr2VfWu%252Fuploads%252FC5rA42yQHcN1uGKFbzmF%252Fnatively_app_builder_bubble_plugin.png%3Falt%3Dmedia%26token%3Dd9706d9b-dbe8-459b-b9b3-5667648aa4b7&#x26;width=768&#x26;dpr=3&#x26;quality=100&#x26;sign=9aae2297&#x26;sv=2" alt=""><figcaption></figcaption></figure>
{% endtab %}

{% tab title="JavaScript SDK" %}
**Check SDK**

Before writing any logic, ensure the Natively SDK is correctly installed and up-to-date in your codebase.

1. Open your project's main HTML file (or header settings) and look for the Natively script tag inside the `<head>` section.
2. Install/Update: If missing or outdated, add the following code. You can specify the SDK version in the URL (e.g., `@2.26.0`).

```javascript
<head>
  <script async onload="nativelyOnLoad()" src="https://cdn.jsdelivr.net/npm/natively@2.26.0/natively-frontend.min.js"></script>
</head>
```

{% hint style="info" %}
To ensure you are using the most up-to-date version, check the [Natively GitHub releases page](https://github.com/buildnatively/js-sdk/releases) for the latest version number.
{% endhint %}
{% endtab %}

{% tab title="AI Agents" %}
**Initialize the SDK**

AI-powered editors like Lovable, Base44, and Replit use the JavaScript SDK to implement Natively features. Before implementing any feature, the Natively SDK must be initialized in your project.

Copy the line below and paste it into your AI agent to check and set up the Natively SDK in your project.

```
Check if the following Natively SDK script is present in the <head> of index.html. If missing or outdated, add it: <script async onload="nativelyOnLoad()" src="https://cdn.jsdelivr.net/npm/natively@2.26.0/natively-frontend.min.js"></script><script>function nativelyOnLoad() { window.natively.setDebug(true); console.log("✅ Natively SDK loaded successfully."); }</script> For reference: https://docs.buildnatively.com/guides/integration/how-to-get-started https://github.com/buildnatively/js-sdk/releases
```

{% endtab %}
{% endtabs %}

### &#x20;Setup logic

{% tabs %}
{% tab title="Bubble.io Plugin" %}

#### Natively - Apple Sign In

#### Events:

* Apple Sign In Success
* Apple Sign In Failed

#### States:

* Email
* Given Name
* Family Name
* Error
* Subject - unique identifier based on your app + user iCloud (it's unique)
* Initial Sign In - means that the user signs in/signs up for the first time to your app

#### Actions:

* Sign In with Apple

#### How to use Sign In with Apple in Bubble

* Add **Natively - Apple Sign In** element on the page.

* Create a "Sign In with Apple" button (you can use a simple image or HTML/CSS). Find some examples [here](https://appleid.apple.com/signinwithapple/button).<br>

  <figure><img src="/files/4XeJbhmj4KQ1vKZayFh8" alt=""><figcaption></figcaption></figure>

* Add "Apple Sign In Success" event and the following actions<br>

  <figure><img src="/files/yeCZY41yKYcMnXrNWXYv" alt=""><figcaption></figcaption></figure>

{% endtab %}

{% tab title="JavaScript SDK" %}

```javascript
// ============================================================================
// NATIVELY SIGN IN WITH APPLE - DOCUMENTATION & EXAMPLES
// ============================================================================

// Initialize
const appleService = new NativelyAppleSignInService();

// ============================================================================
// ALL AVAILABLE METHODS
// ============================================================================
// appleService.signin(callback);
//   - Triggers the native Apple Sign In prompt.

// ============================================================================
// CALLBACK RESPONSE FIELDS
// ============================================================================
// resp.status           - Boolean. true if sign-in was successful, false if failed.
// resp.email            - The user's email. Only available on the first sign-in.
// resp.subject          - Unique identifier tied to the user's iCloud account.
//                         Use this as your primary user identifier in your database.
// resp.givenname        - The user's first name. Only available on the first sign-in.
// resp.familyname       - The user's last name. Only available on the first sign-in.
// resp.initial          - Boolean. true if this is the user's first sign-in to your app.
// resp.jwt              - A JWT issued by Apple for the authenticated user.
// resp.authorizationCode - A short-lived verification code for this authorization.
//                         Must be validated by your server with Apple within 5 minutes.
// resp.message          - Error message. Only present if resp.status is false.

// --- Sign In with Apple. Example. Start ---

const apple_signin_callback = function(resp) {
    if (resp.status) {
        console.log(resp.email);
        console.log(resp.subject);          // unique identifier based on your app + user iCloud (it's unique)
        console.log(resp.givenname);
        console.log(resp.familyname);
        console.log(resp.initial);          // true if user signed in/up for the first time
        console.log(resp.jwt);              // JWT issued by Apple for the authenticated user
        console.log(resp.authorizationCode); // must be validated server-side within 5 minutes
    } else {
        console.log(resp.message);
    }
};

appleService.signin(apple_signin_callback);

// --- Sign In with Apple. Example. End ---
```

{% endtab %}

{% tab title="AI Agents" %}
AI-powered editors like Lovable, Base44, and Replit use the JavaScript SDK to implement Natively features.

Copy the line below and paste it into your AI agent.

<pre><code>[<a data-footnote-ref href="#user-content-fn-1">Your feature description</a>] using the Natively Sign In with Apple SDK: const appleService = new NativelyAppleSignInService(); // appleService.signin(callback) — triggers the native Apple Sign In prompt. // Callback response: resp.status (boolean) — true if successful. resp.email — user email, only available on first sign in. resp.subject — unique user identifier, use as primary user ID. resp.givenname — first name, only on first sign in. resp.familyname — last name, only on first sign in. resp.initial — true if first sign in. resp.jwt — JWT issued by Apple. resp.authorizationCode — must be validated server-side within 5 minutes. resp.message — error message if status is false. For reference: https://docs.buildnatively.com/natively-platform/features/social_auth/sign-in-with-apple
</code></pre>

{% hint style="warning" %}
Replace the placeholder at the beginning with a description of what you want to build - for example: "Add a Sign in with Apple button on the login page that creates a new user account on first sign in and logs in returning users".
{% endhint %}
{% endtab %}
{% endtabs %}

### How to use

#### User identification

Always use `subject` as your primary user identifier - it's unique per user per app and never changes, even if the user switches devices or hides their email.

#### Email availability

Apple lets users hide their real email behind a private relay address. This relay address is only returned on the **first sign-in**; on all subsequent logins `email` will be empty if the user chose to hide it. Design your sign-up flow to handle this: capture the email on first login and store it; never rely on it being present on repeat logins.

#### Name availability

Same as email - `givenname` and `familyname` are only returned on the **first sign-in**. Store them immediately after the first successful login. On subsequent logins, these fields will be empty.

#### Show the Sign In with Apple button only on iOS

Since **Sign In with Apple** only works on iOS, make sure the button is only visible to iOS users. Use the [Browser Info](/guides/integration/browser-info.md) feature to detect whether the app is running on iOS, Android, or a web browser, and conditionally show or hide the button accordingly.

#### First-time vs returning users

Use `resp.initial` to distinguish between a new sign-up and a returning login. Run your account creation logic only when `initial` is `true`.

#### Resetting Sign In with Apple for testing

To simulate a first-time sign-in during development, go to **iOS Settings** > **\[Your Name]** > **Password & Security** > **Apps Using Your Apple ID**, find your app, and tap **Stop Using Apple ID**. Your next sign-in will return all fields as if it's a fresh account.

## Troubleshooting

<details>

<summary>The Sign-In button is not working or doing nothing</summary>

Likely causes: feature not enabled in Natively Dashboard, app not rebuilt after enabling, or the Natively Sign In with Apple JS SDK is not being used for this type of login.&#x20;

</details>

<details>

<summary>Email is empty on login</summary>

Expected behavior if the user chooses to hide their email - not a bug. Should be handled in the sign-up flow.

</details>

<details>

<summary>Name fields are empty on login</summary>

Expected behavior on all logins after the first. Should be stored on first sign-in.

</details>

<details>

<summary>Sign-in succeeds, but the user is treated as new every time</summary>

Likely caused by using `email` as the primary identifier instead of `subject`.

</details>

<details>

<summary>User cancelled error</summary>

When the user dismisses the Apple Sign In prompt, `resp.status` returns `false`. Should be handled gracefully without showing an error to the user.

</details>

<details>

<summary>Testing reset not working</summary>

If "Stop Using Apple ID" doesn't appear for the app, the app may not have completed a successful sign-in yet.

</details>

[^1]: Replace this placeholder