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 Branding & SEO → Auth Portal to customize

Login methods
Per-platform login options
Language
Email and password sign-in
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 Branding → Auth Portal. You customize the Auth Portal’s colors, logo, terms and conditions, privacy policy and more. Learn more here. Go to Branding → 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
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

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, Apple’s App Store guideline 4.8 rejects iOS apps that show social logins that fail inside the app. Detect the mobile app at runtime and sign in with providers=email_otp so those users see email login only, while web and Android keep Google and Apple.

Ask Hercules

When my app runs inside the packaged iOS app, add providers=email_otp to the sign-in redirect so the Auth Portal only shows email login 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 Branding & SEO → 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, Chinese, Japanese, Russian, and Italian.

Hercules Auth Portal sign-in screen shown in Spanish

Setting a default language is available on Pro, Business, and Enterprise plans. Email and password sign-in is available on Pro and Business plans.

Go to Branding & SEO → 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 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:

Column	Required	Description
email	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 Pro and Business plans. No email address is required, and by default you create the accounts: users cannot sign themselves up.

Go to Branding & SEO → 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.

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. 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. To allow it:

Go to Branding & SEO → 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.

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). 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:

Column	Required	Description
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	After connecting your domain in Domains, click Enable auth portal on the domain. Hercules creates the auth domain and shows you the DNS records to add: a CNAME on `auth` pointing to the target shown in your dashboard.

Auth Portal with custom auth domain in browser address bar

The first connected auth domain activates automatically once DNS is verified. To switch between multiple connected domains, or to revert to the default Hercules domain, use the Auth Portal Domain dropdown in Branding → Auth Portal. 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

How do I customize authentication emails?

Go to Branding & SEO → Auth Portal 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 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.

Email customization is available on the Pro plan and above.

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 Branding & SEO → Auth Portal → Login Options, select a provider, and enter your OAuth credentials. After saving, Hercules gives you a Callback URL to add to 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 Callback URL shown in Hercules (you can come back to this step after saving in Hercules)
Click Create
Copy the Client ID and Client Secret

Enter credentials in Hercules

Go to your app’s Auth settings → Google → Custom Credentials.

Paste the Client ID and Client Secret
Click Save
Copy the Callback URL shown after saving

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 Callback URL shown in Hercules (you can come back to this step after saving 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 your app’s Auth settings → Microsoft → Custom Credentials.

Paste the Client ID (Application ID from Microsoft) and Client Secret (secret value)
Click Save
If you haven’t added the Callback URL yet, copy it now and add it to the Redirect URIs in Microsoft Entra

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 your app’s Auth settings → Apple → Custom 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 Save

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 your app’s Auth settings → LinkedIn → Custom Credentials.

Paste the Client ID and Client Secret
Click Save

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 Callback URL shown in Hercules (you can come back to this step after saving 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 your app’s Auth settings → Facebook → Custom Credentials.

Paste the App ID (as Client ID) and App secret (as Client Secret)
Click Save
Copy the Callback URL shown after saving and add it under Valid OAuth Redirect URIs in the Meta app if you haven’t already

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.

Get Started

Hercules AI Agent

Build your app

Publish your app

Advanced

Platform Admin

Company

Customize Auth Portal

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

How do I change the Auth Portal language?

How do I import email and password users?

How do I create and manage username users?

How do I import username and password users?

How do I customize the Auth Portal’s domain?

How do I customize authentication emails?

How do I customize OAuth branding?

Can I bring my own auth provider?

Additional FAQ

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

​How do I customize login options?

​How do I limit login options for one platform, like a mobile app?

​How do I change the Auth Portal language?

​How do I enable email and password sign-in?

​How do I import email and password users?

​How do I enable username and password sign-in?

​How do I let users sign up themselves with a username?

​How do I create and manage username users?

​How do I import username and password users?

​How do I customize the Auth Portal’s domain?

​How do I customize authentication emails?

​How do I customize OAuth branding?

​Can I bring my own auth provider?

​Additional FAQ

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

How do I customize login options?

How do I limit login options for one platform, like a mobile app?

How do I change the Auth Portal language?

How do I enable email and password sign-in?

How do I import email and password users?

How do I enable username and password sign-in?

How do I let users sign up themselves with a username?

How do I create and manage username users?

How do I import username and password users?

How do I customize the Auth Portal’s domain?

How do I customize authentication emails?

How do I customize OAuth branding?

Can I bring my own auth provider?

Additional FAQ