# Auth0

Secure, native authentication for your app — powered by Auth0 Universal Login.

[Auth0](https://auth0.com/) is a widely used authentication and authorization platform that handles login, signup, multi-factor authentication, and social login out of the box. Instead of building and maintaining your own authentication system, Auth0 lets you offload all of that complexity to a battle-tested service.

WebToNative's Auth0 plugin integrates the official [Auth0 iOS SDK](https://github.com/auth0/Auth0.swift) and [Auth0 Android SDK](https://github.com/auth0/Auth0.Android) directly into your app. This means your users get a **native login experience** — including Universal Login, biometric authentication (Face ID, Touch ID, Fingerprint), and automatic session management with refresh tokens — all without leaving your app.

### Why use native Auth0 instead of web-based login?

Mobile security best practices (and policies from Google, Apple, and the [IETF](https://datatracker.ietf.org/doc/html/rfc8252)) require that user authentication happen in a secure browser session facilitated by a native app — not inside an embedded WebView. Auth0 Universal Login satisfies this requirement. WebToNative's plugin handles the entire native flow so you don't have to.

{% hint style="info" %}
**Prerequisites:** Import the WebToNative JavaScript bridge into your website before using any of the functions below. See the [Getting Started](https://docs.webtonative.com/javascript-apis/getting-started) guide.
{% endhint %}

***

## Step 1 — Configure Your Auth0 Account

Before enabling the plugin in WebToNative, you need to set up a Native Application in your Auth0 dashboard.

{% hint style="info" %}
**Note:** The steps below demonstrate a typical configuration. Auth0 is highly customizable — consult the [Auth0 Native App Quickstart Guide](https://auth0.com/docs/quickstart/native) and your Auth0 team for production-ready settings.
{% endhint %}

{% stepper %}
{% step %}

#### Create a Native Application

1. Log in to the [Auth0 Dashboard](https://manage.auth0.com/).
2. Navigate to **Applications → Create Application**.
3. Select **Native** as the application type and click **Create**.
   {% endstep %}

{% step %}

#### Configure Callback and Logout URLs

Under **Settings → Application URIs**, add the following to both **Allowed Callback URLs** and **Allowed Logout URLs**:

**Android callback URL format:**

```
YOUR_SCHEME://YOUR_AUTH0_DOMAIN/android/YOUR_PACKAGE_NAME/callback
```

**iOS callback URL format:**

```
YOUR_SCHEME://YOUR_AUTH0_DOMAIN/ios/YOUR_BUNDLE_ID/callback
```

Here's where each placeholder value comes from:

| Placeholder         | Where to find it                                                        |
| ------------------- | ----------------------------------------------------------------------- |
| `YOUR_AUTH0_DOMAIN` | Auth0 Dashboard → Application → Settings → Domain                       |
| `YOUR_PACKAGE_NAME` | WebToNative Dashboard → App Info → Package Name                         |
| `YOUR_BUNDLE_ID`    | The Bundle ID you created in App Store Connect (must match WebToNative) |
| `YOUR_SCHEME`       | The URL scheme you'll enter in WebToNative's Auth0 plugin settings      |

**Example** (using sample values):

| Key             | Value                       |
| --------------- | --------------------------- |
| Auth0 Domain    | `dev-abc123.us.auth0.com`   |
| Android Package | `com.example.android.myapp` |
| iOS Bundle ID   | `com.example.ios.myapp`     |
| Scheme          | `myapp`                     |

This would result in callback URLs:

```
myapp://dev-abc123.us.auth0.com/android/com.example.android.myapp/callback
myapp://dev-abc123.us.auth0.com/ios/com.example.ios.myapp/callback
```

Add these to **both** the Allowed Callback URLs and Allowed Logout URLs fields (comma-separated).
{% endstep %}

{% step %}

#### Enable Refresh Tokens

Go to **Advanced Settings → OAuth** and turn on **Allow Offline Access**. This is required for refresh tokens to work, which in turn powers auto-login and biometric re-authentication.
{% endstep %}

{% step %}

#### Configure Device Settings

Under **Advanced Settings → Device Settings**, fill in your iOS Team ID and App ID, as well as your Android Package Name and Key Hashes. This ensures Auth0 can verify your app's identity on each platform.
{% endstep %}
{% endstepper %}

***

## Step 2 — Configure the Plugin in WebToNative

{% stepper %}
{% step %}

1. Open your **WebToNative Dashboard → Add-ons → Auth0**.
2. Enter the following values:

   | Field       | Description                                                        |
   | ----------- | ------------------------------------------------------------------ |
   | `Domain`    | Your Auth0 tenant domain (e.g. `dev-abc123.us.auth0.com`)          |
   | `Client ID` | The Client ID from your Auth0 Application Settings                 |
   | `Scheme`    | The URL scheme used in your callback URLs (e.g. `myapp`)           |
   | `Audience`  | *(Optional)* Your Auth0 API audience, if you're using a custom API |

{% endstep %}

{% step %}
3\. Configure **Deep Linking** for your Auth0 domain so that callback redirects are routed back to your app after the user completes Universal Login. Without this, the login flow will complete in the browser but the tokens won't be delivered back to your app.

* **iOS:** Set up Universal Links by hosting a `/.well-known/apple-app-site-association` file on your Auth0 domain (or use the custom URL scheme configured above). See [Deep Linking](https://www.webtonative.com/support/linkhandling/deeplinking) for setup instructions.
* **Android:** Set up App Links by hosting a `/.well-known/assetlinks.json` file on your Auth0 domain, or rely on the custom URL scheme. See [Deep Linking](https://www.webtonative.com/support/linkhandling/deeplinking) for details.
  {% endstep %}

{% step %}
4\. Configure the **URL Scheme Protocol** in your WebToNative dashboard to match the scheme you entered above (e.g. `myapp`). This is the custom scheme Auth0 uses to redirect back to your app (e.g. `myapp://dev-abc123.us.auth0.com/...`). See [URL Scheme Protocol](https://www.webtonative.com/support/linkhandling/urlscheme).
{% endstep %}

{% step %}
5\. Verify that your Auth0 domain is treated as an **external link** in your app's link handling configuration, so that Auth0 login pages open in a secure browser session rather than the app's WebView. See [Internal vs External Linking](https://www.webtonative.com/support/linkhandling/internalvsexternal).
{% endstep %}
{% endstepper %}

***

## JavaScript API Reference

### Login

Opens the Auth0 Universal Login screen. On success, returns OAuth tokens. Optionally stores credentials with biometric protection for seamless future logins.

{% tabs %}
{% tab title="Plain JavaScript" %}

```javascript
window.WTN.Auth0.login({
  scope: "openid profile email offline_access",
  enableBiometrics: true,
  callback: function (response) {
    if (response.error) {
      console.error("Login failed:", response.error);
      return;
    }
    console.log("Access Token:", response.accessToken);
    console.log("ID Token:", response.idToken);
    console.log("Refresh Token:", response.refreshToken);
  },
});
```

{% endtab %}

{% tab title="ES5+ Module" %}

```javascript
import { login } from "webtonative/build/Auth0";

login({
  scope: "openid profile email offline_access",
  enableBiometrics: true,
  callback: (response) => {
    if (response.error) {
      console.error("Login failed:", response.error);
      return;
    }
    console.log("Access Token:", response.accessToken);
    console.log("ID Token:", response.idToken);
    console.log("Refresh Token:", response.refreshToken);
  },
});
```

{% endtab %}
{% endtabs %}

**Parameters:**

| Key                | Type       | Required | Description                                                                                      |
| ------------------ | ---------- | -------- | ------------------------------------------------------------------------------------------------ |
| `scope`            | `String`   | No       | OAuth scopes to request. Include `offline_access` to receive a refresh token.                    |
| `enableBiometrics` | `Boolean`  | No       | If `true`, saves credentials to device secure storage with biometric protection (Face ID, etc.). |
| `callback`         | `Function` | No       | Function invoked with the login response.                                                        |

**Response:**

| Key            | Type     | Description                                             |
| -------------- | -------- | ------------------------------------------------------- |
| `accessToken`  | `String` | The OAuth access token.                                 |
| `idToken`      | `String` | The OpenID Connect ID token.                            |
| `refreshToken` | `String` | The refresh token (requires `offline_access` in scope). |
| `scope`        | `String` | The granted scopes.                                     |
| `error`        | `String` | Error message, present only if login failed.            |

***

### Logout

Clears saved credentials from device secure storage and ends the Auth0 session.

{% tabs %}
{% tab title="Plain JavaScript" %}

```javascript
window.WTN.Auth0.logout({
  callback: function (response) {
    if (response.error) {
      console.error("Logout failed:", response.error);
      return;
    }
    console.log("Logged out successfully");
  },
});
```

{% endtab %}

{% tab title="ES5+ Module" %}

```javascript
import { logout } from "webtonative/build/Auth0";

logout({
  callback: (response) => {
    if (response.error) {
      console.error("Logout failed:", response.error);
      return;
    }
    console.log("Logged out successfully");
  },
});
```

{% endtab %}
{% endtabs %}

**Parameters:**

| Key        | Type       | Required | Description                                |
| ---------- | ---------- | -------- | ------------------------------------------ |
| `callback` | `Function` | No       | Function invoked with the logout response. |

**Response:**

| Key       | Type      | Description                            |
| --------- | --------- | -------------------------------------- |
| `success` | `Boolean` | `true` if logout was successful.       |
| `error`   | `String`  | Error message, present only if failed. |

***

### Get Status

Checks whether the user has a valid saved session and whether biometric authentication is available on the device. Use this to decide whether to show a login screen or attempt auto-login with biometrics.

{% tabs %}
{% tab title="Plain JavaScript" %}

```javascript
window.WTN.Auth0.getStatus({
  callback: function (response) {
    if (response.hasValidCredentials) {
      // User has a saved session — attempt getCredentials()
    } else {
      // No saved session — show login screen
    }
  },
});
```

{% endtab %}

{% tab title="ES5+ Module" %}

```javascript
import { getStatus } from "webtonative/build/Auth0";

getStatus({
  callback: (response) => {
    if (response.hasValidCredentials) {
      // User has a saved session — attempt getCredentials()
    } else {
      // No saved session — show login screen
    }
  },
});
```

{% endtab %}
{% endtabs %}

**Parameters:**

| Key        | Type       | Required | Description                                |
| ---------- | ---------- | -------- | ------------------------------------------ |
| `callback` | `Function` | No       | Function invoked with the status response. |

**Response:**

| Key                   | Type      | Description                                                                    |
| --------------------- | --------- | ------------------------------------------------------------------------------ |
| `hasValidCredentials` | `Boolean` | `true` if the user has saved credentials and the access token has not expired. |
| `biometryAvailable`   | `Boolean` | `true` if Face ID, Touch ID, or Fingerprint authentication is available.       |
| `biometryType`        | `String`  | The type of biometric available: `"faceId"`, `"touchId"`, or `"none"`.         |

***

### Get Credentials

Retrieves saved credentials from device secure storage. If biometrics were enabled during login, the user will be prompted with Face ID or Fingerprint automatically. If the saved access token has expired, it is automatically renewed using the stored refresh token.

{% tabs %}
{% tab title="Plain JavaScript" %}

```javascript
window.WTN.Auth0.getCredentials({
  callback: function (response) {
    if (response.error) {
      console.error("No saved credentials:", response.error);
      return;
    }
    // Use response.accessToken to make authenticated API calls
    console.log("Access Token:", response.accessToken);
  },
});
```

{% endtab %}

{% tab title="ES5+ Module" %}

```javascript
import { getCredentials } from "webtonative/build/Auth0";

getCredentials({
  callback: (response) => {
    if (response.error) {
      console.error("No saved credentials:", response.error);
      return;
    }
    console.log("Access Token:", response.accessToken);
  },
});
```

{% endtab %}
{% endtabs %}

**Parameters:**

| Key        | Type       | Required | Description                                     |
| ---------- | ---------- | -------- | ----------------------------------------------- |
| `callback` | `Function` | No       | Function invoked with the credentials response. |

**Response:**

| Key            | Type     | Description                                       |
| -------------- | -------- | ------------------------------------------------- |
| `accessToken`  | `String` | The OAuth access token (auto-renewed if expired). |
| `idToken`      | `String` | The OpenID Connect ID token.                      |
| `refreshToken` | `String` | The refresh token.                                |
| `error`        | `String` | Error message, present only if retrieval failed.  |

***

### Renew Credentials

Manually renews expired tokens using a refresh token. If no `refreshToken` parameter is provided, the plugin automatically uses the token saved from the last successful login.

> In most cases you don't need to call this directly — `getCredentials()` already handles auto-renewal. Use `renew()` only if you need explicit control over the renewal flow.

{% tabs %}
{% tab title="Plain JavaScript" %}

```javascript
window.WTN.Auth0.renew({
  callback: function (response) {
    if (response.error) {
      console.error("Renewal failed:", response.error);
      return;
    }
    console.log("Renewed Access Token:", response.accessToken);
  },
});
```

{% endtab %}

{% tab title="ES5+ Module" %}

```javascript
import { renew } from "webtonative/build/Auth0";

renew({
  callback: (response) => {
    if (response.error) {
      console.error("Renewal failed:", response.error);
      return;
    }
    console.log("Renewed Access Token:", response.accessToken);
  },
});
```

{% endtab %}
{% endtabs %}

**Parameters:**

| Key            | Type       | Required | Description                                                           |
| -------------- | ---------- | -------- | --------------------------------------------------------------------- |
| `refreshToken` | `String`   | No       | A specific refresh token to use. If omitted, the saved token is used. |
| `callback`     | `Function` | No       | Function invoked with the renewal response.                           |

**Response:**

| Key            | Type     | Description                            |
| -------------- | -------- | -------------------------------------- |
| `accessToken`  | `String` | The renewed OAuth access token.        |
| `idToken`      | `String` | The renewed OpenID Connect ID token.   |
| `refreshToken` | `String` | The renewed refresh token.             |
| `error`        | `String` | Error message, present only if failed. |

***

## Typical Implementation Flow

Here's how a typical authentication flow looks using the Auth0 plugin:

{% stepper %}
{% step %}

#### App launch

Call `getStatus()` to check if the user has saved credentials.
{% endstep %}

{% step %}

#### Returning user

If `hasValidCredentials` is `true`, call `getCredentials()`. The user is prompted with biometrics (if enabled) and receives fresh tokens automatically.
{% endstep %}

{% step %}

#### New user / expired session

If no valid credentials exist, call `login()` with `enableBiometrics: true` and `scope: "openid profile email offline_access"`. Auth0 Universal Login opens natively.
{% endstep %}

{% step %}

#### Use tokens

Send the `accessToken` in your API calls as a Bearer token in the `Authorization` header.
{% endstep %}

{% step %}

#### Logout

Call `logout()` to clear saved credentials and end the session.
{% endstep %}
{% endstepper %}

***

## Implementation Checklist

### Auth0 Dashboard

* [ ] Created a new **Native** application in Auth0
* [ ] Added **Allowed Callback URLs** and **Allowed Logout URLs** for both Android and iOS
* [ ] Enabled **Allow Offline Access** under Advanced Settings → OAuth
* [ ] Filled in **Device Settings** (iOS Team ID/App ID, Android Package Name/Key Hashes)

### WebToNative Dashboard

* [ ] Entered **Domain**, **Client ID**, and **Scheme** in Add-ons → Auth0
* [ ] Configured [**URL Scheme Protocol**](https://www.webtonative.com/support/linkhandling/urlscheme) matching the scheme set in Auth0 (e.g. `myapp`)
* [ ] Configured [**Deep Linking**](https://www.webtonative.com/support/linkhandling/deeplinking) for your Auth0 domain so callback redirects return to the app
* [ ] Verified Auth0 domain is set as an [external link](https://www.webtonative.com/support/linkhandling/internalvsexternal) so login opens in a secure browser

### Your Website

* [ ] Imported the [WebToNative JavaScript bridge](https://docs.webtonative.com/javascript-apis/getting-started)
* [ ] Implemented `login()` to launch Auth0 Universal Login
* [ ] Implemented `logout()` to give users a way to sign out
* [ ] Used `getStatus()` + `getCredentials()` for seamless returning-user login
* [ ] Hosted `.well-known/assetlinks.json` (Android) and `.well-known/apple-app-site-association` (iOS) for deep linking

***

## Frequently Asked Questions

<details>

<summary>Why use the native Auth0 plugin instead of Auth0 in the WebView?</summary>

Mobile security policies from Google, Apple, and the IETF require authentication to happen in a secure browser session — not inside an embedded WebView. The WebToNative Auth0 plugin uses Auth0's official native SDKs, which satisfy these requirements and provide the best security and user experience.

</details>

<details>

<summary>Can biometrics be tested in simulators?</summary>

No. Face ID, Touch ID, and Fingerprint authentication require a physical device with biometric hardware. Use a real device for testing biometric features.

</details>

<details>

<summary>What scopes should I request?</summary>

At minimum, include `openid profile email`. Add `offline_access` if you want refresh tokens (recommended for biometric re-login and persistent sessions).

</details>

<details>

<summary>What happens if the access token expires?</summary>

If you call `getCredentials()`, expired tokens are automatically renewed using the stored refresh token. You can also call `renew()` manually if you need explicit control.

</details>

<details>

<summary>Do I need to set up deep linking?</summary>

Yes. Auth0 uses redirect-based authentication, which relies on deep links to return control to your app after the login flow completes. You'll need to configure both a [URL Scheme](https://www.webtonative.com/support/linkhandling/urlscheme) and [Deep Linking](https://www.webtonative.com/support/linkhandling/deeplinking) in your WebToNative dashboard. For iOS, this means hosting an `apple-app-site-association` file; for Android, an `assetlinks.json` file on your domain.

</details>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.webtonative.com/javascript-apis/auth0-1.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.