Skip to main content
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 → Customize Auth Portal to customize
Login and OTP email customization

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

Go to Branding → Customize Auth Portal. You customize the Auth Portal’s colors, logo, terms and conditions, privacy policy and more. Learn more here.

​
How do I customize login options?

Go to Branding → Customize Auth Portal in the sidebar to enable specific login methods for your users
MethodDefaultDescription
GoogleOnSign in with a Google account
AppleOnSign in with an Apple ID
MicrosoftOnSign in with a Microsoft account (personal or work)
Email OTPOnSign in with a one-time code sent to email
Email and passwordOffCreate an account and sign in with a password
Username and passwordOffAdmin-created accounts; sign in with a username, no email required
FacebookOffSign in with a Facebook account
LinkedInOffSign in with a LinkedIn account
Login method toggle settings
Changes take effect within about a minute. Your users will see the updated options on their next visit to the Auth Portal.

​
How do I change the Auth Portal language?

Go to Branding & SEO → Customize 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, and German.
Hercules Auth Portal sign-in screen shown in Spanish
Setting a default language is available on Pro, Business, and Enterprise plans.

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

Email and password sign-in is available on Pro and Business plans.
  1. Go to Branding & SEO → Customize Auth Portal.
  2. Under Sign-in Methods, turn on Email and password.
  3. 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:
  1. Enable and save Email and password sign-in.
  2. Click Import users beside the sign-in method.
  3. Choose a CSV file and click Review users.
  4. Review the valid, skipped, and invalid rows.
  5. Click Import users.
The CSV can be up to 5 MB and must use these columns:
ColumnRequiredDescription
emailYesA valid email address
passwordYesBetween 8 and 128 characters
nameNoThe 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.

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

Username and password sign-in is available on Pro and Business plans. Unlike other methods, you create the accounts: users cannot sign themselves up, and no email address is required.
  1. Go to Branding & SEO → Customize Auth Portal.
  2. Under Sign-in Methods, turn on Username and password.
  3. Save your changes.
  4. Click Manage users beside the sign-in method to create 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.

​
How do I create and manage username users?

Because there is no self-signup and no email on the account, you handle account creation and password resets.
  1. Enable and save Username and password sign-in.
  2. Click Manage users beside the sign-in method.
  3. To add a user, enter a username and set a password (or generate one), then share the credentials with the user.
  4. To reset a password (for example when a user forgets theirs), find the user, 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:
  1. Enable and save Username and password sign-in.
  2. Click Import users beside the sign-in method.
  3. Choose a CSV file and click Review users.
  4. Review the valid, skipped, and invalid rows.
  5. Click Import users.
The CSV can be up to 5 MB and must use these columns:
ColumnRequiredDescription
usernameYes3 to 30 characters: letters, numbers, underscores, and periods
passwordYesBetween 8 and 128 characters
nameNoThe 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 setupWhat to do
Purchased through HerculesNothing. auth.yourdomain.com is configured automatically.
3rd party domainAfter 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 → Customize Auth Portal. Additional notes
  1. SSL is provisioned automatically
  2. To use a subdomain other than auth, contact hello@hercules.app
  3. 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 → Customize Auth Portal to customize the emails your users receive during authentication:
FieldDescription
Login Code Email SenderSender for login codes, email verification, and password reset messages. Configure a sender identity in Hercules Email first to use your own domain.
From AddressThe local part before @yourdomain.com (for example, noreply or auth). Shown only when you select a domain identity.
Email SubjectThe subject line of the email one-time passcode message.
App NameThe name used in email content and verification or password reset subject lines.
Email FooterA custom signature used in login code, verification, and password reset messages.
Login and OTP email customization
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 → Customize 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.
1

Create a Google Cloud project

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

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

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
4

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
5

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
1

Register an app in Microsoft Entra ID

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
2

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

Copy the Client ID

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

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

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 Sign In requires more setup than other providers because Apple uses a private key instead of a simple client secret.
1

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
2

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
3

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

Find your Team ID

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

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
1

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
2

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

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
4

Enter credentials in Hercules

Go to your app’s Auth settings → LinkedIn → Custom Credentials.
  • Paste the Client ID and Client Secret
  • Click Save
1

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
2

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)
3

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
4

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

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
Custom OAuth credentials form
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 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 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.