Getting started and concepts
What's the difference between MFA, adaptive MFA, and step-up authentication?
What's the difference between MFA, adaptive MFA, and step-up authentication?
MFA (Multi-Factor Authentication):
- Requires additional authentication after primary credentials (username/password)
- Applied consistently to all users or specific groups
- Example: Always require SMS OTP after password login
- Uses rules to intelligently determine when to challenge users based on risk factors
- Challenges users only when necessary (new device, suspicious location, etc.)
- Balances security with user experience
- Requires additional verification for sensitive operations, even if already logged in
- Applied to specific high-risk actions (payments, account changes)
- Example: Require passkey verification before processing a large transaction
What are actions and rules in Authsignal?
What are actions and rules in Authsignal?
Actions represent security events in your application that may require additional verification:
- Login attempts, payments, account changes, data access
- Each action returns one of four outcomes:
ALLOW,CHALLENGE,REVIEW, orBLOCK - Have configurable default outcomes
- Evaluate risk factors like device characteristics, IP data, user behavior
- Can override action default outcomes based on context
- Enable adaptive authentication policies
What are the four action outcomes and what do they mean?
What are the four action outcomes and what do they mean?
When you track an action, Authsignal returns one of four possible states:
ALLOW- Action is permitted without additional authentication. Proceed with the user’s request.CHALLENGE_REQUIRED- User must complete an authentication challenge before proceeding.BLOCK- Action is blocked for security reasons. Deny the user’s request.REVIEW- Action requires manual review before proceeding.
CHALLENGE_REQUIRED is returned.Configuration and setup
Why should I use custom domains?
Why should I use custom domains?
Custom domains are a pre-requisite when using passkeys. Outside of this scenario, custom domains are optional but highly recommended as they help to create a more branded and trusted user experience.
What are the different ways to use WhatsApp OTP with Authsignal?
What are the different ways to use WhatsApp OTP with Authsignal?
As a standalone authentication method:
- Users receive OTP codes directly via WhatsApp as their primary phone-based authentication
- Configured independently in the Authenticators section
- Follow our WhatsApp OTP guide for implementation
- WhatsApp automatically delivers OTP codes when SMS delivery fails or is unavailable
- Helps reduce messaging costs while maintaining reliable delivery
- Configured within the SMS OTP settings as a backup channel
- See the SMS OTP guide for setup instructions
Passkeys
How can I determine if a device has a passkey available?
How can I determine if a device has a passkey available?
The approach differs between web and mobile platforms:For web applications:
Use the WebAuthn API’s conditional UI feature (passkey autofill) which only shows passkeys when they’re available on the device. This provides a seamless experience without requiring explicit detection.For mobile applications:
Handle error codes when passkey authentication fails to provide graceful fallback experiences. Present a “Sign in” button that immediately displays the passkey prompt for the optimal experience when passkeys are available, then gracefully fall back to email authentication when they’re not.For detailed implementation guidance and code examples, see our web best practices and mobile best practices guides.
How do passkeys make sign-in easier than other methods?
How do passkeys make sign-in easier than other methods?
Unlike traditional methods where you type your username first, passkeys can show you available accounts automatically without any typing.Traditional sign-in (username-initiated):
- You enter your username/email first
- The site looks up your account
- Then sends you a code or prompts for a password
- Your device shows available passkeys automatically
- You select which account to use
- Authentication happens instantly with biometrics or device PIN
What is passkey uplift and when should I use it?
What is passkey uplift and when should I use it?
Passkey uplift is the process of prompting users to create a passkey after they’ve successfully signed in using a traditional method like email OTP or password. This helps transition users gradually from legacy authentication to passkeys.When to show passkey uplift:
- After a user completes email/SMS OTP authentication
- When a user signs in on a new device without a passkey
- During onboarding flows for new users
- After password-based sign-ins
- Explain the benefits clearly (faster, more secure, no passwords to remember)
- Make it optional, not mandatory
- Use timed cooldowns to avoid being intrusive
- Show the prompt at natural transition points in your app
Why aren't passkeys always available, and how should I handle this?
Why aren't passkeys always available, and how should I handle this?
Passkeys may not be available on a device for several reasons:
- User created a passkey on one device but switched to a new device where it can’t be synced
- User deleted the passkey from their password manager
- Switching between iOS and Android devices (cross-platform sync limitations)
Should I use passkey autofill or a dedicated sign-in button?
Should I use passkey autofill or a dedicated sign-in button?
Both approaches have their benefits:Passkey Autofill (Recommended for Web)
- Unobtrusive way to support passkeys while maintaining familiar UX
- Only shows passkeys if already created and available on device
- Users can manually enter username if no passkey is available
- Particularly good option when you already have a username input on your existing username and password login page
- Clear alternative authentication option
- Launches passkey prompt regardless of availability
- May show QR code if no passkey available (can be confusing for some users)
How should I handle passkeys for MFA vs. primary authentication?
How should I handle passkeys for MFA vs. primary authentication?
For MFA (Secondary Factor):
- Use
allowCredentialsparameter to restrict passkeys to the specific user’s credentials - Only show passkeys for one account to avoid confusion on shared devices
- Still provide backup options as the device may not have the user’s passkeys
- Can show all available passkeys on device
- Device-initiated flow allows users to select from available credentials
- Focus on smooth fallback experience when no passkeys are present
How can I increase passkey adoption among my users?
How can I increase passkey adoption among my users?
Gradual Introduction:
- Prompt users to create passkeys after they sign in with existing methods
- Provide clear explanations of passkey benefits (faster, more secure, no passwords)
- Use gentle prompts rather than forcing immediate adoption
- Prompt users to create passkeys when they authenticate on new devices
- Consider enrollment flows that create backup authentication methods first
- Use timed cooldowns or behavior-based prompts to avoid being intrusive
- Display passkeys using credential manager names (iCloud Keychain, Google Password Manager)
- Show appropriate icons using
webauthnCredential.aaguidMappingdata - Help users understand which devices their passkeys are available on
Should I create passkeys before or after other authentication methods on mobile?
Should I create passkeys before or after other authentication methods on mobile?
Best practice: Create backup authentication first, then passkeys.Unlike web where users can easily switch between devices, mobile users often switch between iOS and Android where passkeys don’t sync. Always ensure users have a backup option:Recommended flow:This approach prevents users from getting locked out when switching between platforms or devices where their passkey isn’t available.
- User signs up and completes email OTP or SMS OTP enrollment
- After successful enrollment, prompt to create a passkey
- User now has both a backup method and a convenient passkey
What is `preferImmediatelyAvailableCredentials` and when should I use it?
What is `preferImmediatelyAvailableCredentials` and when should I use it?
This parameter controls whether to show the passkey prompt when no credentials are available on the device.When set to
true (recommended):- Only shows passkey prompt if credentials exist on the current device
- Avoids confusing QR code prompts for users without passkeys
- Enables smooth fallback to email/SMS authentication
false:- Always shows passkey prompt, even with no local credentials
- May display QR code for cross-device authentication
- Can be confusing for users unfamiliar with passkey cross-device flows
true for most mobile apps to ensure users aren’t presented with QR codes when they don’t have passkeys available locally.Push notifications
Does Authsignal push authentication rely on push notifications?
Does Authsignal push authentication rely on push notifications?
It’s a common misconception that Push Authentication relies on push notifications (like FCM or APNs) to function. In fact, Authsignal’s Push Authentication is built to work even without them.Push authentication uses device credentials and public key cryptography - the push notification is only used to prompt users to open the app. If the notification doesn’t arrive, users can still open the app manually and complete authentication.
Can I use my own push notification provider?
Can I use my own push notification provider?
Can I customize the push message content and branding?
Can I customize the push message content and branding?
Yes, you have full control over push notifications’ content, language, and appearance. Since Authsignal integrates with your existing push infrastructure via webhooks, you control all aspects of the notification including the message text, images, sounds, and branding.
Authenticators and user management
Are there limits on how many OTP codes users can send or verify?
Are there limits on how many OTP codes users can send or verify?
In order to deter and protect challenge flows from abuse and high volume attacks, Authsignal has built-in rate limits for different authenticator types.These limits are in place to deter and stop bad actors and typically will not be noticed by legitimate users on your platform.Rate limits for sendingThe following limits apply when sending emails or SMS to initiate a challenge.
Rate limits for verificationThe following limits apply when submitting OTP codes to complete a challenge.
| Authenticator type | Rate limit |
|---|---|
| Email magic link | 12 per 10 mins |
| Email OTP | 12 per 10 mins |
| SMS OTP | 6 per 10 mins |
| Authenticator type | Rate limit |
|---|---|
| Email OTP | 10 per 5 mins |
| SMS OTP | 10 per 5 mins |
| Time-based OTP (TOTP) | 10 per 5 mins |
Can I remove authenticators for a user?
Can I remove authenticators for a user?
Yes, you can remove authenticators for users in two ways:Through the Authsignal Portal:
- Navigate to the user details page
- Click the “Remove authenticators” button
- Select which authenticators you want to remove and submit
API and integration
The track API call is returning a 401 HTTP status code
The track API call is returning a 401 HTTP status code
Please check your API secret key and API URL are correct. You can find the values for your tenant in the Authsignal Portal under Settings -> API keys. Ensure that the API URL corresponds to your tenant’s region.
The track API call is returning `AUTHENTICATOR_NOT_FOUND` with a 400 HTTP status code
The track API call is returning `AUTHENTICATOR_NOT_FOUND` with a 400 HTTP status code
This error is returned when no authenticators have been configured for your tenant.
Where can I get the `deviceId`?
Where can I get the `deviceId`?
If you’re using the Authsignal Web SDK, a cookie named If reading the request cookie is not an option, you can use retrieve the
__as_aid is set on the user’s browser.When tracking an action on your server, you can extract the deviceId from this cookie:Server
deviceId on the client via authsignal.anonymousId
and pass it to your server in the request body:Client
Webhooks
Why is my webhook signature verification failing?
Why is my webhook signature verification failing?
The most common cause is framework manipulation of the request body. The Authsignal SDK requires the raw body to verify signatures.Common issues:
- Framework parsing JSON and converting back to string
- Body compression/decompression
- Character encoding changes
- Middleware modifying the request
Which IP addresses do Authsignal webhooks come from?
Which IP addresses do Authsignal webhooks come from?
For IP whitelisting, Authsignal sends webhooks from these addresses:
Make sure to whitelist the IP addresses for your tenant’s region.
| Region | IP Addresses |
|---|---|
| US (Oregon) | 44.224.97.232 44.230.210.235 44.236.208.22 52.33.85.88 |
| AU (Sydney) | 13.210.81.243 3.105.80.107 54.252.129.142 |
| EU (Dublin) | 34.247.148.106 34.253.116.90 54.171.116.55 |
Error handling and troubleshooting
How can an action get into a `CHALLENGE_FAILED` state?
How can an action get into a `CHALLENGE_FAILED` state?
There are currently only two scenarios where this can occur:
- In push notification auth when the user presses “Deny” instead of “Accept” in the in-app notification
- In SMS or email OTP auth when the number of code submission attempts exceeds rate limit thresholds
CHALLENGE_FAILED state.What are the common SDK error codes and what do they mean?
What are the common SDK error codes and what do they mean?
invalid_configuration: Your tenant configuration is invalid. Check that authenticators are properly configured in the Authsignal Portal.invalid_credential: The credential (e.g., passkey) is invalid for the user. This may happen if the credential was deleted or is being used on the wrong device.invalid_request: Request failed due to invalid parameters. Check your request payload and ensure all required fields are provided.too_many_requests: Rate limit exceeded. Implement back-off and retry logic.unauthorized: Invalid tenant credentials or wrong region. Verify your API secret key and API URL match your tenant’s region.See our error handling documentation for implementation examples.How do I know which region my tenant is in?
How do I know which region my tenant is in?
You can find your region information in the Authsignal Portal under Settings -> API Keys. The API URL will indicate your region:
- US (Oregon):
https://api.authsignal.com/v1 - AU (Sydney):
https://au.api.authsignal.com/v1 - EU (Dublin):
https://eu.api.authsignal.com/v1
unauthorized errors.Why am I getting CORS errors with the Authsignal APIs?
Why am I getting CORS errors with the Authsignal APIs?
Authsignal APIs are designed to be called from your backend, not directly from frontend JavaScript in browsers.Correct flow:
- Frontend sends request to your backend
- Your backend calls Authsignal APIs
- Your backend returns response to frontend
- Use the pre-built UI (hosted by Authsignal, no CORS issues)
- Use our Client SDKs for custom UI implementations