Skip to main content
Common authentication issues and how to fix them.
OTP emails can be blocked by corporate or secure mail servers (common with Outlook and other business email environments), or by email antivirus software at the company level. Here’s what to try:
  1. Check your spam/junk folder — the email may have been filtered.
  2. Try a different login method or email — Google, Apple, or Microsoft sign-in will bypass OTP delivery entirely. If your corporate email is on a secured server, a Gmail or personal address will work immediately.
  3. Ask your IT team to add our sending domains to your allowlist:
    • hercules.app
    • notifications.hercules.app
    This is the most common fix for users on corporate or secured email environments. Once allowlisted, OTPs should come through reliably.
  4. Email antivirus blocking — if your company uses email antivirus software, it may be intercepting OTP emails. If you know the name of your provider, share it when you contact us so we can investigate.
If the issue persists, reach out at hello@hercules.app.
  1. Check spam or junk. Verification and password reset messages can be filtered.
  2. Confirm the email address. The password reset screen shows the same confirmation whether an account exists or not, so check that the user entered the address on their account.
  3. Allowlist the sender. Without a custom sender, allowlist hercules.app and notifications.hercules.app. If you use your own sender, allowlist that domain instead.
  4. Check your sender identity. If you configured a custom sender, confirm it is still verified under Email.
If the issue persists, reach out at hello@hercules.app.
Safari’s Intelligent Tracking Prevention clears script-writable storage (including the session token) after about 7 days without interaction with your app. This affects Safari on both iOS and macOS, and WebKit-based browsers on iOS. Chrome, Firefox, and Edge on desktop or Android are not affected.Ask Hercules to fix it:
Fix Safari sign-outs
Users stay signed in as long as they open the app at least once every 30 days. Sessions refresh automatically in the background, so active users stay signed in indefinitely.If a user does not open the app for 30 days, they will be asked to sign in again.Session length is the same for every sign-in method. Email code, Google, Apple, Microsoft, and single sign-on all end at the same place, so none of them gives a user a longer or shorter session than the others.
Yes. The app holds a short-lived token that lasts one hour, and @usehercules/auth renews it about a minute before it runs out. You do not need to add anything for this to work.Renewal is a direct call to the sign-in service, not a hidden frame, so it does not depend on third-party cookies. That means renewal works the same in a saved home-screen app as it does in a browser tab.Keep the sign-in package on one exact version. By default your app can pick up a newer build of @usehercules/auth the next time it installs, so two builds of the same app can behave differently. Ask Hercules to lock it:
Lock the sign-in package version
If users are signed out sooner than 30 days, check these in order:
  1. Safari or iOS. See the “Why do my users keep getting logged out?” section above.
  2. Incognito or private mode, or a browser set to clear site data on close. The session is wiped when the tab closes.
  3. New device or browser. Each browser holds its own session. Signing in somewhere new does not carry over.
  4. Signed out from somewhere else. If the user, an admin, or another tab signs out, all of that user’s sessions end.
  5. Something misconfigured in the app’s auth setup. Ask Hercules to check it:
Check auth setup
If none of these fit, click “Support & feedback” with the user’s email and roughly when the sign-out happened. The Hercules team can check server logs from there.
Saved home-screen apps work with Hercules Auth, and sign-in state lives in the saved app’s own storage. Two things come up with saved apps:
  1. Retry the first call after a long sleep. A phone can suspend the app for hours, and the renewal timer does not catch up the instant the screen wakes, so the first data call can go out with a token that has already run out. Have that call retry once after a failure rather than showing an error, which gives the renewal time to land. Reloading the page also works, because a reload re-checks an expired token before rendering.
  2. An update that does not appear on iPhone or iPad means the saved app is running an older copy. Remove the icon from the home screen, open the site once in Safari, then add it to the home screen again. Android picks up updates on its own.
Ask Hercules to add the retry:
Retry the first call after sleep
Hercules Auth uses Cloudflare Turnstile (a captcha alternative) to verify your users during login. If the verification widget does not load or gets stuck, your users can try these steps:
  1. Update the browser. Turnstile supports all major browsers except Internet Explorer. Make sure the browser is up to date.
  2. Disable browser extensions. Ad blockers and privacy extensions can block the scripts Turnstile needs. Temporarily disable all extensions and reload the page.
  3. Confirm JavaScript is enabled. Turnstile requires JavaScript. Check the browser settings to make sure it is on.
  4. Try incognito or private mode. This rules out issues caused by extensions or cached data.
  5. Test in another browser or device. This confirms whether the issue is specific to one setup.
  6. Disable VPNs or proxies. Some VPNs and proxies interfere with Turnstile. Turn them off temporarily and try again.
  7. Switch networks. Some networks block the requests Turnstile needs. Try a mobile hotspot or different Wi-Fi.
  8. Run the compatibility check. Open Cloudflare’s Turnstile troubleshooter in the same browser where the issue occurs and share the results when contacting support.
If none of these steps help, click “Support & feedback” in the sidebar or email hello@hercules.app with a screenshot of the issue and the troubleshooter results.
Make sure the CNAME record is correctly added in your DNS settings. The Name field should be auth, not the full domain (e.g. not auth.yourdomain.com). DNS propagation usually takes a few minutes but can take up to a few hours in rare cases.If you use Cloudflare, make sure the CNAME record for the auth subdomain is set to DNS only (gray cloud icon), not Proxied (orange cloud icon). Cloudflare proxying can interfere with the SSL certificate provisioning.If it has been more than 24 hours, contact hello@hercules.app.
This is a Google Safe Browsing warning, usually triggered by the apex domain rather than the auth subdomain itself. See Google Safe Browsing warnings on your domain for the Search Console verification and review request flow.
Google OAuth apps start in Testing mode with a 100-user limit. To remove this limit, go to APIs & Services → OAuth consent screen and click Publish App. Google may require a verification review, which can take several days.
Apple only allows you to download the .p8 private key file once. You will need to create a new key in the Apple Developer portal and update the credentials in Hercules. See the Apple setup guide for full steps.
  1. Ask Hercules to configure auth like in the Hercules Auth debugging guide 2. Accept any changes it recommends 3. If the login captcha or verification widget is not loading, see “Why is the login captcha not working?” above 4. If still not working, click “Support & feedback” in the sidebar and the Hercules team will help
This means the Callback URL in the provider’s developer console does not match the one Hercules uses. Go to your app’s Auth settings, copy the Callback URL, and make sure it is entered exactly (including https://) in the provider’s redirect URI settings. See the OAuth branding guide for provider-specific steps.
Changes take effect within about a minute after saving. If you created your OAuth app at the provider, allow a few minutes for the provider to propagate the credentials.
You can request a new OTP code by restarting the login process.
  1. Ask Hercules to configure auth like in the Hercules Auth debugging guide 2. Check whether a browser extension, antivirus, or network is blocking the connection 3. If everything is correct and it still fails, contact support