#### What does Hercules SMS cost? Hercules charges \$0.08 per successful verification. Extra charges may apply based on the recipient's country or resends. Enter a country to see the estimated cost per successful verification.

Unfinished verifications are charged only for the messages sent. Charges are billed to your Hercules Cloud credits and can appear in the next billing period. Hercules SMS sends codes to most countries. Some countries restrict sender names or message content. Test sign-in from each country you plan to support before you turn on SMS sign-in. #### How do I check that sign-in works? 1. Open your app in **Preview**, then open its real sign-in page. The visual **Login Preview** in settings cannot send messages. 2. Select your country and request a code using a phone you control. This can send a billable SMS. 3. Confirm the code arrives and use it to finish signing in. A successful save only stores your settings. Simulated test numbers do not reach a real phone. Repeat the real sign-in check for the destination countries you plan to support. Each code lasts 5 minutes and allows 3 verification attempts. A new code can be requested after 60 seconds. If codes stop arriving, check your Hercules Cloud credit balance in **Settings** → **Billing** → **Cloud Credits**. Hercules SMS stops sending new codes when credits run out. Confirm your plan and that the destination country is supported. If codes still do not arrive, open **Support & feedback** → **Create a support ticket** with your app and the attempt time in UTC. Do not include phone numbers or sign-in codes. ### How do I customize OAuth branding? By default, your users see "Hercules" on the OAuth consent screen during social login. Use custom credentials to show your brand name, privacy policy, and terms of service instead. Go to **Users & Access** → **Auth Portal** → **Sign-in Methods**, click **Configure** next to your provider, and choose **Your app's credentials**. Copy the **Redirect URI** shown in the dialog to add as the callback URL in your provider's developer console. See provider-specific guides below. Go to the [Google Cloud Console](https://console.cloud.google.com/). Create a new project or select an existing one. Go to **APIs & Services** → **OAuth consent screen**. * Set the **User Type** to **External** (unless you are restricting to a Google Workspace organization) * Fill in the **App name**, **User support email**, and **Developer contact email** * Add your logo, privacy policy URL, and terms of service URL * Under **Scopes**, add `openid`, `email`, and `profile` * Save Google OAuth apps start in "Testing" status with a 100-user limit. To remove this limit, click **Publish App** and complete Google's verification process. This can take several days. Go to **APIs & Services** → **Credentials** → **Create Credentials** → **OAuth client ID**. * Set **Application type** to **Web application** * Under **Authorized redirect URIs**, add the **Redirect URI** shown in Hercules * Click **Create** * Copy the **Client ID** and **Client Secret** Go to **Users & Access** → **Auth Portal** → **Sign-in Methods**, click **Configure** next to **Google**, and choose **Your app's credentials**. * Paste the **Client ID** and **Client Secret** * Copy the **Redirect URI** shown in the dialog * Click **Done**. In **Auth Portal**, turn on **Google** when you are ready, then click **Save changes** Go back to the Google Cloud Console → **APIs & Services** → **Credentials** → click your OAuth client. * Under **Authorized redirect URIs**, add the Callback URL from Hercules * Save Go to the [Microsoft Entra admin center](https://entra.microsoft.com/) → **Identity** → **App registrations** → **New registration**. * Set a **Name** for the app (your users will see this) * Under **Supported account types**, select **Accounts in any organizational directory and personal Microsoft accounts** (this covers both work and personal accounts) * Under **Redirect URI**, select **Web** and enter the **Redirect URI** shown in Hercules * Click **Register** In your app registration, go to **Certificates & secrets** → **New client secret**. * Add a description and choose an expiry period * Click **Add** * Copy the **Value** (this is your Client Secret, shown only once) Copy the secret value immediately. Microsoft only shows it once. If you lose it, you will need to create a new secret. Go to **Overview** in your app registration. Copy the **Application (client) ID**. If a user's email already has an account from another method (Google, email code), signing in with a Microsoft work or school account shows "account was signed up using a different method". This clears once Microsoft confirms the user's organization owns the email domain, which it reports through the `xms_edov` claim. Add that claim and these accounts link automatically. (Personal Microsoft accounts verify their own email and are unaffected.) In your app registration, open **Manifest** and make `optionalClaims.idToken` include `email` and `xms_edov`: ```json optionalClaims in the app manifest wrap theme={} "optionalClaims": { "idToken": [ { "name": "email", "source": null, "essential": false }, { "name": "xms_edov", "source": null, "essential": false } ] } ``` Save, then the affected user signs in with **Continue with Microsoft** and links automatically. You do not need to change your supported account types. `xms_edov` is not in the **Token configuration** dropdown, so add it through the Manifest; a "claim not recognized" warning there is safe to ignore. Go to **Users & Access** → **Auth Portal** → **Sign-in Methods**, click **Configure** next to **Microsoft**, and choose **Your app's credentials**. * Paste the **Client ID** (Application ID from Microsoft) and **Client Secret** (secret value) * If you haven't added the callback URL yet, copy the **Redirect URI** shown in the dialog and add it to **Redirect URIs** in Microsoft Entra * Click **Done**. In **Auth Portal**, turn on **Microsoft** when you are ready, then click **Save changes** Apple Sign In requires more setup than other providers because Apple uses a private key instead of a simple client secret. Go to the [Apple Developer portal](https://developer.apple.com/account/resources/identifiers/list) → **Certificates, Identifiers & Profiles** → **Identifiers** → click **+**. * Select **App IDs** → **Continue** * Select **App** → **Continue** * Enter a **Description** and a **Bundle ID** (e.g. `com.yourcompany.yourapp`) * Under **Capabilities**, check **Sign In with Apple** * Click **Continue** → **Register** Go to **Identifiers** → click **+** → select **Services IDs** → **Continue**. * Enter a **Description** (your users will see this on the Apple consent screen) * Enter an **Identifier** (e.g. `com.yourcompany.yourapp.auth`) * Click **Continue** → **Register** Then click on your new Services ID: * Check **Sign In with Apple** → click **Configure** * Under **Domains and Subdomains**, add the domain shown in the Hercules Callback URL (for example, `hercules-auth.com`) * Under **Return URLs**, add the full **Callback URL** from Hercules * Click **Save** → **Continue** → **Save** Go to **Keys** → click **+**. * Enter a **Key Name** * Check **Sign In with Apple** → click **Configure** * Select the **App ID** you created in Step 1 * Click **Save** → **Continue** → **Register** * **Download** the `.p8` key file. Store it securely. Apple only lets you download it once. * Note the **Key ID** shown on this page The `.p8` private key file can only be downloaded once. If you lose it, you must create a new key. Go to **Membership details** in the Apple Developer portal. Copy your **Team ID** (a 10-character string). Go to **Users & Access** → **Auth Portal** → **Sign-in Methods**, click **Configure** next to **Apple**, and choose **Your app's credentials**. * **Client ID**: Enter the **Identifier** of your Services ID (from Step 2, e.g. `com.yourcompany.yourapp.auth`) * **Team ID**: Paste your Team ID * **Key ID**: Paste the Key ID from Step 3 * **Private Key**: Open the `.p8` file in a text editor and paste the entire contents, including the `-----BEGIN PRIVATE KEY-----` and `-----END PRIVATE KEY-----` lines * Click **Done**. In **Auth Portal**, turn on **Apple** when you are ready, then click **Save changes** Go to the [LinkedIn Developer Portal](https://www.linkedin.com/developers/apps) → **Create App**. * Enter an **App name**, **LinkedIn Page**, and **Logo** * Accept the terms and click **Create app** In your app's **Products** tab, find **Sign In with LinkedIn using OpenID Connect** and click **Request access**. Go to the **Auth** tab. * Under **Authorized redirect URLs for your app**, add the **Callback URL** from Hercules * Copy the **Client ID** and **Client Secret** Go to **Users & Access** → **Auth Portal** → **Sign-in Methods**, click **Configure** next to **LinkedIn**, and choose **Your app's credentials**. * Paste the **Client ID** and **Client Secret** * Click **Done**. In **Auth Portal**, turn on **LinkedIn** when you are ready, then click **Save changes** Go to [Meta for Developers](https://developers.facebook.com/apps) → **Create app**. * Choose the **Authenticate and request data from users with Facebook Login** use case * Enter an **App name** and contact email, then create the app Go to **App settings** → **Basic**. * Add a **Privacy Policy URL** and a **User data deletion** URL (both required to go live) * Set a **Category** * Copy the **App ID** and **App secret** (click **Show**) Open the **Facebook Login** use case → **Settings**. * Turn on **Client OAuth login** and **Web OAuth login** * Under **Valid OAuth Redirect URIs**, add the **Redirect URI** shown in Hercules * Save In the Facebook Login use case → **Permissions and features**, confirm **email** and **public\_profile** have advanced access. Switch the app to **Live** mode so people outside your app roles can sign in. Go to **Users & Access** → **Auth Portal** → **Sign-in Methods**, click **Configure** next to **Facebook**, and choose **Your app's credentials**. * Paste the **App ID** (as Client ID) and **App secret** (as Client Secret) * Copy the **Redirect URI** shown in the dialog and add it under **Valid OAuth Redirect URIs** in the Meta app if you haven't already * Click **Done**. In **Auth Portal**, turn on **Facebook** when you are ready, then click **Save changes**

**Additional notes** * If you remove custom credentials, Hercules automatically falls back to its own managed credentials. Social login continues to work. Your users will see "Hercules" on the consent screen again. * Custom OAuth credentials are available on the **Business plan** ### Can I bring my own auth provider? Currently, Hercules apps only support Hercules Auth. Authentication is a fragile part of building software. If auth breaks, your entire app can break. We prioritize making Hercules Auth a stable, well-supported, secure, and robust auth system. We are working on supporting custom auth providers in the future. ### Additional FAQ Your app likely uses the previous Hercules Auth. [Upgrade to Hercules Auth 2.0](/docs/apps/users-auth/upgrade-to-hercules-auth-2) to unlock provider toggles, your own developer accounts, custom auth domain, and email customization. **Auth** is how your users prove their identity (sign in / sign up). **Users** is where you manage the people who have signed up for your app, including their roles, permissions, and account status. Configure auth options here; manage your user base in the [Users, Roles & Permissions](/docs/apps/users-auth/users-roles-permissions) tab. Yes. Hercules Auth blocks throwaway and temporary email addresses (like Mailinator, Guerrilla Mail, etc.) by default for email one-time passcodes and email and password. Social sign-ins are not blocked by this check. Split the users across multiple CSV files with no more than 5,000 rows in each file. Yes. Imported users can use **Forgot password?** immediately. Yes. The import continues in the background. Open **Import users** again to see its current status. Each app can run one import at a time. Accounts created by the first import are skipped and left unchanged. Rows that previously failed validation can be imported after you fix them. Not currently. Hercules Auth works by redirecting to a Hercules-hosted Auth Portal. We are working on allowing in-app authentication flows in the near future. No. Existing users can sign in with any enabled method that matches their email address. If a user signed up with Google and you later enable Apple, they can sign in with Apple using the same email and both accounts are automatically linked. No. The callback URL must be your site URL. It cannot be localhost. The auth domain is still reserved by the app you moved the domain from. In that app, go to **Users & Access** → **Auth Portal** and click **Remove** next to the auth domain under **Auth Portal Domain**. Then click **Enable auth portal** on the domain in the new app's **Domains** tab. The **Create User** button is available on every plan, including Free. It stays inactive until username and password sign-in is enabled. To fix: 1. Go to **Users & Access → Auth Portal** 2. Turn on **Username and password** under **Sign-in Methods** 3. Save The button becomes active immediately. If it still shows a paid plan message, refresh the page. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.