Customize Auth Portal

Customize every aspect of your login experience, from which sign-in methods your users see to branding on the OAuth consent screen.

These features require Hercules Auth 2.0. Apps created before Hercules Auth 2.0 shipped need to upgrade to use them.

Go to Users & Access → Auth Portal to customize

Login methods
Per-platform login options
Language
Theme
Email and password sign-in
Add a first password
Import email and password users
Username and password sign-in
Username self-signup
Create and manage username users
Import username and password users
Authentication emails
Auth Portal domain
OAuth consent screen branding

How do I customize Auth Portal logo, colors, and appearance?

Go to Users & Access → Auth Portal. You customize the Auth Portal’s logo, theme (system, light, or dark), terms and conditions, privacy policy and more. Go to Users & Access → Auth Portal in the sidebar to enable specific login methods for your users

Method	Default	Description
Google	On	Sign in with a Google account
Apple	On	Sign in with an Apple ID
Microsoft	On	Sign in with a Microsoft account (personal or work)
Email OTP	On	Sign in with a one-time code sent to email
SMS OTP	Off	Sign in with a one-time code sent by text message (Pro, Business, and Enterprise plans)
Email and password	Off	Create an account and sign in with a password
Username and password	Off	Sign in with a username, no email required; accounts are admin-created unless you enable self-signup
Facebook	Off	Sign in with a Facebook account
LinkedIn	Off	Sign in with a LinkedIn account
Single sign-on (SSO)	Off	Sign in with your organization’s identity provider (Business and Enterprise plans)

Sign-in methods with SMS OTP and its Pro plan badge

Changes take effect within about a minute. Your users will see the updated options on their next visit to the Auth Portal. Add a providers query parameter to your app’s sign-in redirect to show only specific login methods for that request. Other platforms keep the full set you enabled. This helps packaged mobile apps. For example, show fewer methods in your iOS app while web and Android keep every method. Two Apple rules apply: the App Review demo account must sign in with a password, and guideline 4.8 asks apps that offer Google or another social sign-in to also offer an equivalent private option, such as Sign in with Apple. See how sign-in works in the store app.

Ask Hercules

When my app runs inside the packaged iOS app (the user agent contains HerculesNative and iPhone), add providers=email_password,apple to the sign-in redirect so the Auth Portal only shows those methods there

Accepted values (comma-separated): google, apple, microsoft, facebook, linkedin, email_otp, email_password, phone_otp, username_password. The parameter only hides methods. It cannot enable a method you turned off, and the Auth Portal ignores it if no requested method is enabled.

How do I change the Auth Portal language?

Go to Users & Access → Auth Portal and choose a language under Default Language. The Auth Portal shows sign-in, sign-up, one-time codes, password reset, and account settings in that language for all your users. Hercules supports English, Spanish, French, German, Portuguese (Brazil), Portuguese (Portugal), Chinese, Japanese, Russian, Italian, Arabic, Croatian, Slovenian, and Dutch.

Hercules Auth Portal sign-in screen shown in Spanish

Setting a default language is available on Pro, Business, and Enterprise plans.

How do I change the Auth Portal’s theme?

Go to Users & Access → Auth Portal and choose System, Light, or Dark under Theme. System follows each visitor’s device setting; Light and Dark use that theme for every visitor. Existing apps stay on Light until you change it. Setting a theme is available on Pro, Business, and Enterprise plans. Email and password sign-in is available on every plan, including Free.

Go to Users & Access → Auth Portal.
Under Sign-in Methods, turn on Email and password.
Save your changes.

Your users will see Continue with email & password on the Auth Portal. New users enter their name, email address, and a password between 8 and 128 characters. Hercules rejects temporary email addresses and passwords found in known data breaches. Hercules sends new users a verification link that expires after 24 hours. They must verify their email before signing in. Users can click Forgot password? on the sign-in screen to request a reset link. The link expires after one hour. Resetting a password signs the user out of their existing sessions.

How does an existing user add their first password?

Users who already sign in with Google, Apple, Microsoft, or an email code can add email and password without creating another account:

Enable and save Email and password sign-in.
Ask the user to sign in with their existing method.
Ask the user to open Account settings on the Auth Portal.
Under Set a password, click Email me a link.
Open the link in the email and set a password.

The new password is added to the existing user. Their user ID and linked app data stay the same, and their original sign-in method continues to work. Do not ask the user to sign up again.

How do I import email and password users?

Users on the Business plan can import up to 5,000 users at a time:

Enable and save Email and password sign-in.
Go to Users & Access → Users and click Import Users.
Choose a CSV file and click Review users.
Review the valid, skipped, and invalid rows.
Click Import users.

The CSV can be up to 5 MB and must use these columns. The Users import flow uses the same email_or_username identifier column for both email and username accounts. For this section, put a valid email address in that column.

Column	Required	Description
email_or_username	Yes	A valid email address
password	Yes	Between 8 and 128 characters
name	No	The user’s name. Hercules uses the email prefix when omitted.

Do not include other columns. Header names are not case-sensitive. Imported users are marked as verified and can sign in immediately. Hercules does not send verification emails or credentials during the import. Existing accounts and duplicate emails are skipped and never changed. Invalid rows are not imported. Download the report after review or completion to see the reason for each skipped or invalid row.

The CSV contains passwords in plain text. Store and share it securely, then delete it after the import.

Username and password sign-in is available on every plan. No email address is required, and by default you create the accounts: users cannot sign themselves up.

Go to Users & Access → Auth Portal.
Under Sign-in Methods, turn on Username and password.
Save your changes.
Go to Users & Access → Users and click Create User to add accounts.

The Create User button stays inactive until Username and password is enabled and saved. It is available on every plan, including Free. Your users will see Continue with username & password on the Auth Portal. Usernames are 3 to 30 characters and can contain letters, numbers, underscores, and periods. Passwords are 8 to 128 characters, and Hercules rejects passwords found in known data breaches. Use this method when your users do not have email addresses, or when you want to provision accounts yourself, for example staff logins or a closed user base. Self-signup is off by default and needs a paid plan. To allow it:

Go to Users & Access → Auth Portal.
Under Sign-in Methods, click Configure beside Username and password.
Turn on Allow users to sign up themselves.
Choose how usernames are set: users pick their own, or Hercules assigns one automatically. For assigned usernames you can add a prefix, for example cust_ produces usernames like cust_84739215.
Save your changes.

The Auth Portal then shows a Sign up tab for the method. With assigned usernames, new users only choose a password; the portal shows their generated username once, on a confirmation screen, before returning them to your app. Self-signup accounts still have no email, so there is no Forgot password? email flow: a forgotten password is reset by you, the same as for accounts you create. Self-signup only applies while Username and password is on. If the method is off and your plan does not include self-signup, turning the method back on turns self-signup off with it, and you keep creating accounts yourself. Apps that already have self-signup running keep it.

How do I create and manage username users?

Because there is no email on the account, you handle account creation (unless self-signup is enabled) and all password resets.

Enable and save Username and password sign-in.
Go to Users & Access → Users.
To add a user, click Create User, enter a username and set a password (or generate one), then share the credentials with the user.
To reset a password (for example when a user forgets theirs), open the user’s actions menu, choose Reset password, set a new password, and share it. Resetting a password signs the user out of their existing sessions.

Once signed in, a user can change their own password on the Auth Portal settings page (/settings on your Auth Portal domain). The new password must be 8 to 128 characters and must not appear in a known data breach. Those are the only rules: Hercules does not require a mix of numbers, symbols, or letter cases, and it does not compare the new password with the old one. There is no Forgot password? email flow for username accounts, since the account has no email: a forgotten password is reset by you.

How do I import username and password users?

Users on the Business plan can import up to 5,000 username accounts at a time:

Enable and save Username and password sign-in.
Go to Users & Access → Users and click Import Users.
Choose a CSV file and click Review users.
Review the valid, skipped, and invalid rows.
Click Import users.

The CSV can be up to 5 MB and must use these columns. Put a valid username in the email_or_username column. A single file can include email and username rows when both sign-in methods are enabled.

Column	Required	Description
email_or_username	Yes	3 to 30 characters: letters, numbers, underscores, and periods
password	Yes	Between 8 and 128 characters
name	No	The user’s name. Hercules uses the username when omitted.

Do not include other columns. Header names are not case-sensitive, and usernames are matched case-insensitively. Imported users can sign in immediately. Existing usernames and duplicate rows are skipped and never changed. Invalid rows are not imported. Download the report after review or completion to see the reason for each skipped or invalid row.

The CSV contains passwords in plain text. Store and share it securely, then delete it after the import.

How do I customize the Auth Portal’s domain?

By default, the Auth Portal uses a Hercules-managed domain (e.g. yourapp.hercules-auth.com). You can change this to auth.yourdomain.com so your users see your domain during sign-in. Configuration depends on how you connect your domain to your Hercules app.

Domain setup	What to do
Purchased through Hercules	Nothing. `auth.yourdomain.com` is configured automatically.
3rd party domain	When you connect your domain in Domains, Hercules creates the auth domain automatically. Add the `auth` CNAME record shown in your dashboard. If you don’t see the `auth` record, click Enable auth portal on the domain.

Auth Portal with custom auth domain in browser address bar

Once DNS is verified, the first auth domain is selected automatically in the Auth Portal Domain dropdown in Users & Access → Auth Portal. Use the same dropdown to switch between multiple connected domains or revert to the default Hercules domain. Additional notes

SSL is provisioned automatically
To use a subdomain other than auth, contact hello@hercules.app
If users see a red “Deceptive site ahead” or “Dangerous site” warning when visiting auth.yourdomain.com, the flag typically originates from your apex domain. See Google Safe Browsing warnings on your domain
If auth.yourdomain.com fails for users in some countries or on some networks, see My auth domain fails for users in certain countries or networks

How do I customize authentication emails?

Go to Users & Access → Auth Portal. Under Sign-in Methods, click Configure next to Email one-time passcode to customize the emails your users receive during authentication:

Field	Description
Login Code Email Sender	Sender for login codes, email verification, and password reset messages. Configure a sender identity in Hercules Email first to use your own domain.
From Address	The local part before `@yourdomain.com` (for example, `noreply` or `auth`). Shown only when you select a domain identity.
Email Subject	The subject line of the email one-time passcode message.
App Name	The name shown on your sign-in page and its browser tab title, and used in email content and verification or password reset subject lines.
Email Footer	A custom signature used in login code, verification, and password reset messages.

When you finish editing, click Done, then click Save changes in Auth Portal.

Email customization is available on the Pro plan and above. Hercules SMS sends sign-in codes by text message. You do not need to write code, host a server, or set up an SMS account. Hercules sends the messages and bills you through Hercules Cloud credits. SMS sign-in requires Hercules Auth 2.0, and is available on the Pro, Business, and Enterprise plans. It supports phone sign-up and sign-in. Users cannot add, change, or remove the phone number on an existing account. Prefer your own SMS account? Connect Twilio Messaging, Vonage, Plivo, or 2factor.in. Custom providers are also available on all paid plans and bill you directly instead of using Hercules Cloud credits. The steps below use Hercules SMS.

Go to Users & Access → Auth Portal → Sign-in Methods.
Turn on SMS one-time passcode (OTP).
To change the name in your messages, click Configure next to SMS one-time passcode (OTP), edit App name shown in SMS, and click Done. It defaults to your organization’s name.
Click Save changes.

You can configure SMS while it is off. Save changes applies your settings. Cancel in Auth Portal discards all unsaved changes. Saving does not send a test message. You cannot choose a sending phone number or edit the message text.

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.

Open your app in Preview, then open its real sign-in page. The visual Login Preview in settings cannot send messages.
Select your country and request a code using a phone you control. This can send a billable SMS.
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.

Google setup

Create a Google Cloud project

Go to the Google Cloud Console. Create a new project or select an existing one.

Configure the OAuth consent screen

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.

Create OAuth credentials

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

Enter credentials in Hercules

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

Add the Callback URL to Google

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

Microsoft setup

Go to the Microsoft Entra admin center → 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

Create a client secret

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.

Copy the Client ID

Go to Overview in your app registration. Copy the Application (client) ID.

Optional: auto-link work and school accounts

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:

optionalClaims in the app manifest

"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.

Enter credentials in Hercules

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 setup

Apple Sign In requires more setup than other providers because Apple uses a private key instead of a simple client secret.

Create an App ID

Go to the Apple Developer portal → 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

Create a Services ID

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

Create a private key

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.

Find your Team ID

Go to Membership details in the Apple Developer portal. Copy your Team ID (a 10-character string).

Enter credentials in Hercules

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

LinkedIn setup

Create a LinkedIn app

Go to the LinkedIn Developer Portal → Create App.

Enter an App name, LinkedIn Page, and Logo
Accept the terms and click Create app

Add the Sign In with LinkedIn product

In your app’s Products tab, find Sign In with LinkedIn using OpenID Connect and click Request access.

Configure OAuth redirect

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

Enter credentials in Hercules

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

Facebook setup

Create a Meta app

Go to Meta for Developers → 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

Add your app details

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)

Configure Facebook Login

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

Request access and go live

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.

Enter credentials in Hercules

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

I don't see these options in my dashboard

Your app likely uses the previous Hercules Auth. Upgrade to Hercules Auth 2.0 to unlock provider toggles, your own developer accounts, custom auth domain, and email customization.

What's the difference between users and auth?

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 tab.

Can I block disposable email addresses from signing up?

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.

Can I import more than 5,000 users?

Split the users across multiple CSV files with no more than 5,000 rows in each file.

Can imported users reset their password?

Yes. Imported users can use Forgot password? immediately.

Can I close the window while an import runs?

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.

What happens if I upload the same CSV again?

Accounts created by the first import are skipped and left unchanged. Rows that previously failed validation can be imported after you fix them.

Can I embed auth directly in my app?

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.

Can I use a localhost callback URL?

No. The callback URL must be your site URL. It cannot be localhost.

I moved my domain to another app and its auth domain is already in use

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.

Why is the Create User button grayed out on the Free plan?

The Create User button is available on every plan, including Free. It stays inactive until username and password sign-in is enabled.To fix:

Go to Users & Access → Auth Portal
Turn on Username and password under Sign-in Methods
Save

The button becomes active immediately. If it still shows a paid plan message, refresh the page.

Get Started

Hercules App Builder Agent

Build your app

Publish your app

Advanced

App management

Customize Auth Portal

How do I customize Auth Portal logo, colors, and appearance?