website·Indexed 35 days ago
https://supertokens.com/docsAn open-source authentication provider that gives developers control over user data and the login experience. Documentation covers core authentication, session verification, user roles and permissions, and the Additional Verification suite including MFA (TOTP, WebAuthn/Passkeys, Email/SMS OTP), email verification, and attack protection.
Email delivery is managed independently by the recipes that generate the messages. The following recipes have their own email delivery configurations:
EmailPassword: For password resets.EmailVerification: For email verification codes and links.Passwordless: For email codes and links.WebAuthn: For account-recovery emails.Note: The AccountLinking recipe does not configure email delivery.
SuperTokens provides two ways to handle authorization data. Session Claims are the recommended approach as they provide built-in validation, automatic refresh mechanisms, and graceful failure handling. The Access Token Payload is a simpler, lightweight method for checking static data but lacks automatic validation and refresh capabilities.
Important: Frontend claim checks are for user experience only. All protected APIs must verify the session and enforce claim validators on the backend to prevent unauthorized access.
The Client Credentials Flow is used for machine-to-machine (M2M) authentication where a service (Service A) needs to communicate with another service (Service B) without user intervention.
The sequence is as follows:
SuperTokens provides Multi-Factor Authentication (MFA) to secure applications by requiring users to verify their identity through multiple credentials. Supported MFA factors include:
Key capabilities include 'step-up authentication', which allows developers to require an additional challenge for specific sensitive routes or actions. MFA is available for managed SuperTokens deployments.
Tenant discovery automatically routes users to the appropriate tenant based on the domain of their email address (e.g., user@company.com is routed to the company tenant). It includes built-in protection against popular email providers and falls back to the public tenant when necessary.
Important Security Warning: Tenant discovery is for routing, not authorization. An email domain does not prove ownership or membership. After authentication, you must verify the user's membership in the discovered tenant and derive the tenant from trusted session data for every business-data access.
SuperTokens supports two methods for authorizing requests. The choice of method is controlled by the backend, but it follows a preference set in the frontend configuration via the st-auth-mode header.
HttpOnly cookies to prevent token theft via XSS. Recommended for browsers.Authorization header with a Bearer auth-scheme. Preferred for mobile environments due to unreliable cookie implementations and easier integration with API gateways.Step-up authentication requires users to complete an authentication challenge before navigating to a specific page or performing a sensitive action. It can be implemented as a full-page navigation or as a popup on the current page.
Supported authentication factors include:
Note: Step-up authentication is currently not supported if you are using OAuth2 in your configuration.
SuperTokens supports two password hashing algorithms: BCrypt and Argon2. While Argon2 is recommended per current best practices, BCrypt is used by default because Argon2 requires hardware-specific configuration.
Changing the hashing algorithm only affects new users who sign up; existing passwords remain compatible with the algorithm used at the time of their creation. The target performance metric is approximately 300 milliseconds per hash.