Thrown when handling the redirect callback for the connect flow fails, will be one of Auth0's Authentication API's Standard Error Responses: https://auth0.com/docs/api/authentication?javascript#standard-error-responses
-Thrown when network requests to the Auth server fail.
-Error thrown when initiating an MFA challenge fails.
+try {
const challenge = await mfa.challenge({
mfaToken: mfaToken,
challengeType: 'otp',
authenticatorId: 'otp|dev_123'
});
} catch (error) {
if (error instanceof MfaChallengeError) {
console.log(error.error); // 'too_many_attempts'
console.log(error.error_description); // 'Rate limit exceeded'
}
}
+OptionalstackStatic OptionalprepareOptional override for formatting stack traces
+StaticstackStaticcaptureCreate .stack property on a target object
+OptionalconstructorOpt: FunctionStaticfromError thrown when enrolling an MFA authenticator fails.
+OptionalstackStatic OptionalprepareOptional override for formatting stack traces
+StaticstackStaticcaptureCreate .stack property on a target object
+OptionalconstructorOpt: FunctionStaticfromError thrown when getting enrollment factors fails.
+OptionalstackStatic OptionalprepareOptional override for formatting stack traces
+StaticstackStaticcaptureCreate .stack property on a target object
+OptionalconstructorOpt: FunctionStaticfromBase class for MFA-related errors in auth0-spa-js. +Extends GenericError for unified error hierarchy across the SDK.
+OptionalstackStatic OptionalprepareOptional override for formatting stack traces
+StaticstackStaticcaptureCreate .stack property on a target object
+OptionalconstructorOpt: FunctionStaticfromError thrown when listing MFA authenticators fails.
+OptionalstackStatic OptionalprepareOptional override for formatting stack traces
+StaticstackStaticcaptureCreate .stack property on a target object
+OptionalconstructorOpt: FunctionStaticfromError thrown when the token exchange results in a mfa_required error
Error thrown when verifying an MFA challenge fails.
+try {
const tokens = await mfa.verify({
mfaToken: mfaToken,
grant_type: 'http://auth0.com/oauth/grant-type/mfa-otp',
otp: '123456'
});
} catch (error) {
if (error instanceof MfaVerifyError) {
console.log(error.error); // 'invalid_otp' or 'context_not_found'
console.log(error.error_description); // Error details
}
}
+OptionalstackStatic OptionalprepareOptional override for formatting stack traces
+StaticstackStaticcaptureCreate .stack property on a target object
+OptionalconstructorOpt: FunctionStaticfromError thrown when there is no refresh token to use
-An OAuth2 error will come from the authorization server and will have at least an error property which will
be the error code. And possibly an error_description property
See: https://openid.net/specs/openid-connect-core-1_0.html#rfc.section.3.1.2.6
-Optionalerror_description: stringOptionalerror_description: stringOptionalerror_OptionalstackStatic OptionalprepareOptional override for formatting stack traces
StaticstackThrown when network requests to the Auth server fail.
-Error thrown when the login popup times out (if the user does not complete auth)
-Thrown when silent auth times out (usually due to a configuration issue) or when network requests to the Auth server timeout.
-Error thrown when the wrong DPoP nonce is used and a potential subsequent retry wasn't able to fix it.
-Provides the Auth0Context to its child components.
-Use the useAuth0 hook in your components to access the auth state and methods.
TUser is an optional type param to provide a type to the user field.
Wrap your class components in this Higher Order Component to give them access to the Auth0Context.
Providing a context as the second argument allows you to configure the Auth0Provider the Auth0Context should come from f you have multiple within your application.
-When you wrap your components in this Higher Order Component and an anonymous user visits your component they will be redirected to the login page; after login they will be returned to the page they were redirected from.
-Contains the authenticated state and authentication methods provided by the useAuth0 hook.
await connectAccountWithRedirect({
connection: 'google-oauth2',
scopes: ['openid', 'profile', 'email', 'https://www.googleapis.com/auth/drive.readonly'],
authorization_params: {
// additional authorization params to forward to the authorization server
}
});
@@ -26,7 +27,7 @@
where the user can authenticate and authorize the account to be connected.
If connecting the account is successful onRedirectCallback will be called
with the details of the connected account.
-Returns a new Fetcher class that will contain a fetchWithAuth() method.
+
Returns a new Fetcher class that will contain a fetchWithAuth() method.
This is a drop-in replacement for the Fetch API's fetch() method, but will
handle certain authentication logic for you, like building the proper auth
headers or managing DPoP nonces and retries automatically.
Check the EXAMPLES.md file for a deeper look into this method.
Optionalconfig: FetcherConfig<TOutput>The options required to perform the token exchange
+Optionalconfig: FetcherConfig<TOutput>The options required to perform the token exchange
A promise that resolves to the token endpoint response containing Auth0 tokens
Use loginWithCustomTokenExchange() instead. This method will be removed in the next major version.
const tokenResponse = await exchangeToken({
subject_token: 'external_token_value',
subject_token_type: 'urn:acme:legacy-system-token',
scope: 'openid profile email'
});
@@ -50,13 +51,13 @@
// Instead of:
const tokens = await exchangeToken(options);
// Use:
const tokens = await loginWithCustomTokenExchange(options);
-Returns a string to be used to demonstrate possession of the private +
Returns a string to be used to demonstrate possession of the private key used to cryptographically bind access tokens with DPoP.
It requires enabling the Auth0ClientOptions.useDpop option.
Returns a string to be used to demonstrate possession of the private key used to cryptographically bind access tokens with DPoP.
It requires enabling the Auth0ClientOptions.useDpop option.
-const token = await getAccessTokenSilently(options);
+const token = await getAccessTokenSilently(options);
If there's a valid token stored, return it. Otherwise, opens an @@ -75,7 +76,7 @@ back to using an iframe to make the token exchange.
Note that in all cases, falling back to an iframe requires access to
the auth0 cookie.
const token = await getTokenWithPopup(options, config);
+const token = await getTokenWithPopup(options, config);
Get an access token interactively.
@@ -83,7 +84,7 @@ provided as arguments. Random and securestate and nonce
parameters will be auto-generated. If the response is successful,
results will be valid according to their expiration times.
-const config = getConfiguration();
// { domain: 'tenant.auth0.com', clientId: 'abc123' }
+const config = getConfiguration();
// { domain: 'tenant.auth0.com', clientId: 'abc123' }
Returns a readonly copy of the initialization configuration @@ -93,7 +94,7 @@
Returns the current DPoP nonce used for making requests to Auth0.
+Returns the current DPoP nonce used for making requests to Auth0.
It can return undefined because when starting fresh it will not
be populated until after the first response from the server.
It requires enabling the Auth0ClientOptions.useDpop option.
@@ -108,16 +109,16 @@const claims = await getIdTokenClaims();
+const claims = await getIdTokenClaims();
Returns all claims from the id_token if available.
-After the browser redirects back to the callback page, +
After the browser redirects back to the callback page,
call handleRedirectCallback to handle success and error
responses from Auth0. If the response is successful, results
will be valid according to their expiration times.
Optionalurl: stringThe URL to that should be used to retrieve the state and code values. Defaults to window.location.href if not given.
await loginWithCustomTokenExchange(options);
+await loginWithCustomTokenExchange(options);
Exchanges an external subject token for Auth0 tokens and logs the user in. @@ -141,7 +142,7 @@
const options = {
subject_token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6Ikp...',
subject_token_type: 'urn:acme:legacy-system-token',
scope: 'openid profile email',
audience: 'https://api.example.com',
organization: 'org_12345'
};
try {
const tokenResponse = await loginWithCustomTokenExchange(options);
console.log('Access token:', tokenResponse.access_token);
// User is now logged in - access user info
const user = await getUser();
console.log('Logged in user:', user);
} catch (error) {
console.error('Token exchange failed:', error);
}
await loginWithPopup(options, config);
+await loginWithPopup(options, config);
Opens a popup with the /authorize URL using the parameters
@@ -151,20 +152,35 @@
IMPORTANT: This method has to be called from an event handler that was started by the user like a button click, for example, otherwise the popup will be blocked in most browsers.
-await loginWithRedirect(options);
+await loginWithRedirect(options);
Performs a redirect to /authorize using the parameters
provided as arguments. Random and secure state and nonce
parameters will be auto-generated.
auth0.logout({ logoutParams: { returnTo: window.location.origin } });
+auth0.logout({ logoutParams: { returnTo: window.location.origin } });
Clears the application session and performs a redirect to /v2/logout, using
the parameters provided as arguments, to clear the Auth0 session.
If the logoutParams.federated option is specified, it also clears the Identity Provider session.
Read more about how Logout works at Auth0.
Sets the current DPoP nonce used for making requests to Auth0.
+const { mfa } = useAuth0();
const authenticators = await mfa.getAuthenticators(mfaToken);
+MFA API client for Multi-Factor Authentication operations.
+Provides access to all MFA-related methods:
+getAuthenticators(mfaToken) - List enrolled authenticatorsenroll(params) - Enroll new authenticators (OTP, SMS, Voice, Email, Push)challenge(params) - Initiate MFA challengesverify(params) - Verify MFA challenges and complete authenticationgetEnrollmentFactors(mfaToken) - Get available enrollment factorsconst { mfa, getAccessTokenSilently } = useAuth0();
try {
await getAccessTokenSilently();
} catch (error) {
if (error.error === 'mfa_required') {
// Check if enrollment is needed
const factors = await mfa.getEnrollmentFactors(error.mfa_token);
if (factors.length > 0) {
// Enroll in OTP
const enrollment = await mfa.enroll({
mfaToken: error.mfa_token,
factorType: 'otp'
});
console.log('QR Code:', enrollment.barcodeUri);
}
// Get authenticators and challenge
const authenticators = await mfa.getAuthenticators(error.mfa_token);
await mfa.challenge({
mfaToken: error.mfa_token,
challengeType: 'otp',
authenticatorId: authenticators[0].id
});
// Verify with user's code
const tokens = await mfa.verify({
mfaToken: error.mfa_token,
otp: userCode
});
}
}
+Sets the current DPoP nonce used for making requests to Auth0.
It requires enabling the Auth0ClientOptions.useDpop option.
Sets the current DPoP nonce used for making requests to Auth0.
It requires enabling the Auth0ClientOptions.useDpop option.
@@ -176,4 +192,4 @@The main configuration to instantiate the Auth0Provider.
memory.
Read more about changing storage options in the Auth0 docs
OptionalchildrenThe child nodes your Provider has wrapped
-The Client ID found on your Application settings page
+The Client ID found on your Application settings page
OptionalcontextContext to be used when creating the Auth0Provider, defaults to the internally created context.
This allows multiple Auth0Providers to be nested within the same application, the context value can then be passed to useAuth0, withAuth0, or withAuthenticationRequired to use that specific Auth0Provider to access @@ -48,7 +48,7 @@ used to store data is different
For a sample on using multiple Auth0Providers review the React Account Linking Sample
-OptionalcookieThe domain the cookie is accessible from. If not set, the cookie is scoped to +
OptionalcookieThe domain the cookie is accessible from. If not set, the cookie is scoped to the current domain, including the subdomain.
Note: setting this incorrectly may cause silent authentication to stop working on page load.
@@ -73,7 +73,7 @@OptionalonBy default this removes the code and state parameters from the url when you are redirected from the authorize page.
It uses window.history but you might want to overwrite this if you are using a custom router, like react-router-dom
See the EXAMPLES.md for more info.
OptionalsessionNumber of days until the cookie auth0.is.authenticated will expire
+
OptionalsessionNumber of days until the cookie auth0.is.authenticated will expire
Defaults to 1.
OptionalskipBy default, if the page url has code/state params, the SDK will treat them as Auth0's and attempt to exchange the code for a token. In some cases the code might be for something else (another OAuth SDK perhaps). In these @@ -81,7 +81,7 @@
<Auth0Provider
clientId={clientId}
domain={domain}
skipRedirectCallback={window.location.pathname === '/stripe-oauth-callback'}
>
OptionaluseIf true, the SDK will use a cookie when storing information about the auth transaction while
+
OptionaluseIf true, the SDK will use a cookie when storing information about the auth transaction while
the user is going through the authentication flow on the authorization server.
The default is false, in which case the SDK will use session storage.
You might want to enable this if you rely on your users being able to authenticate using flows that diff --git a/docs/interfaces/Authenticator.html b/docs/interfaces/Authenticator.html new file mode 100644 index 00000000..bc49bbbf --- /dev/null +++ b/docs/interfaces/Authenticator.html @@ -0,0 +1,16 @@ +
Represents an MFA authenticator enrolled by a user
+Whether the authenticator is active
+Type of authenticator
+OptionalcreatedISO 8601 timestamp when created
+Unique identifier for the authenticator
+OptionallastISO 8601 timestamp of last authentication
+OptionalnameOptional friendly name
+OptionaltypeTypes of MFA challenges
+Parameters for initiating an MFA challenge
+Response from initiating an MFA challenge
+Email enrollment parameters
+OTP (Time-based One-Time Password) enrollment parameters
+Push notification enrollment parameters
+SMS enrollment parameters
+Voice enrollment parameters
+OptionalauthorizationURL parameters that will be sent back to the Authorization Server. This can be known parameters defined by Auth0 or custom parameters that you define.
diff --git a/docs/interfaces/LogoutOptions.html b/docs/interfaces/LogoutOptions.html index 36412a2b..ca29bafc 100644 --- a/docs/interfaces/LogoutOptions.html +++ b/docs/interfaces/LogoutOptions.html @@ -1,4 +1,4 @@ -OptionalclientThe clientId of your application.
Client for Auth0 MFA API operations
+Manages multi-factor authentication including:
+This is a wrapper around auth0-auth-js MfaClient that maintains +backward compatibility with the existing spa-js API.
+MFA context (scope, audience) is stored internally keyed by mfaToken, +enabling concurrent MFA flows without state conflicts.
+try {
await auth0.getTokenSilently({ authorizationParams: { audience: 'https://api.example.com' } });
} catch (e) {
if (e instanceof MfaRequiredError) {
// SDK automatically stores context for this mfaToken
const authenticators = await auth0.mfa.getAuthenticators({ mfaToken: e.mfa_token });
// ... complete MFA flow
}
}
+Initiates an MFA challenge
+Sends OTP via SMS, initiates push notification, or prepares for OTP entry
+Challenge parameters including mfaToken
+Challenge response with oobCode if applicable
+Enrolls a new MFA authenticator
+Requires MFA access token with 'enroll' scope
+Enrollment parameters including mfaToken and factorType
+Enrollment response with authenticator details
+Gets enrolled MFA authenticators filtered by challenge types from context.
+Challenge types are automatically resolved from the stored MFA context +(set when mfa_required error occurred).
+MFA token from mfa_required error
+Array of enrolled authenticators matching the challenge types
+Gets available MFA enrollment factors from the stored context.
+This method exposes the enrollment options from the mfa_required error's +mfaRequirements.enroll array, eliminating the need for manual parsing.
+MFA token from mfa_required error
+Array of enrollment factors available for the user (empty array if no enrollment required)
+try {
await auth0.getTokenSilently();
} catch (error) {
if (error.error === 'mfa_required') {
// Get enrollment options from SDK
const enrollOptions = await auth0.mfa.getEnrollmentFactors(error.mfa_token);
// [{ type: 'otp' }, { type: 'phone' }, { type: 'push-notification' }]
showEnrollmentOptions(enrollOptions);
}
}
+try {
const factors = await auth0.mfa.getEnrollmentFactors(mfaToken);
if (factors.length > 0) {
// User needs to enroll in MFA
renderEnrollmentUI(factors);
} else {
// No enrollment required, proceed with challenge
}
} catch (error) {
if (error instanceof MfaEnrollmentFactorsError) {
console.error('Context not found:', error.error_description);
}
}
+InternalStores authentication details (scope, audience, and MFA requirements) for MFA token verification. +This is automatically called by Auth0Client when an mfa_required error occurs.
+The context is stored keyed by the MFA token, enabling concurrent MFA flows.
+The MFA token from the mfa_required error response
+Optionalscope: stringThe OAuth scope from the original request (optional)
+Optionalaudience: stringThe API audience from the original request (optional)
+OptionalmfaRequirements: MfaRequirementsThe MFA requirements from the mfa_required error (optional)
+Verifies an MFA challenge and completes authentication
+The scope and audience are retrieved from the stored context (set when the +mfa_required error occurred). The grant_type is automatically inferred from +which verification field is provided (otp, oobCode, or recoveryCode).
+Verification parameters with OTP, OOB code, or recovery code
+Token response with access_token, id_token, refresh_token
+If grant_type cannot be inferred
+Rate limits:
+const tokens = await mfa.verify({
mfaToken: mfaTokenFromLogin,
otp: '123456'
});
console.log(tokens.access_token);
+Parameters for verifying an MFA challenge.
+The grant_type is automatically inferred from which verification field is provided:
+otp field → MFA-OTP grant typeoobCode field → MFA-OOB grant typerecoveryCode field → MFA-RECOVERY-CODE grant typeOptionalbindingBinding code (for OOB challenges with binding)
+MFA token from challenge flow
+OptionaloobOut-of-band code (for OOB challenges)
+OptionalotpOne-time password (for OTP challenges)
+OptionalrecoveryRecovery code (for recovery code verification)
+Components wrapped in withAuth0 will have an additional auth0 prop
Options for the withAuthenticationRequired Higher Order Component
-OptionalcontextThe context to be used when calling useAuth0, this should only be provided if you are using multiple Auth0Providers within your application and you wish to tie a specific component to a Auth0Provider other than the Auth0Provider associated with the default Auth0Context.
-OptionalloginwithAuthenticationRequired(Profile, {
loginOptions: {
appState: {
customProp: 'foo'
}
}
})
+OptionalloginwithAuthenticationRequired(Profile, {
loginOptions: {
appState: {
customProp: 'foo'
}
}
})
Pass additional login options, like extra appState to the login page.
This will be merged with the returnTo option used by the onRedirectCallback handler.
OptionalonwithAuthenticationRequired(Profile, {
onBeforeAuthentication: () => { analyticsLibrary.track('login_triggered'); }
})
+OptionalonwithAuthenticationRequired(Profile, {
onBeforeAuthentication: () => { analyticsLibrary.track('login_triggered'); }
})
Allows executing logic before the user is redirected to the login page.
-OptionalonwithAuthenticationRequired(Profile, {
onRedirecting: () => <div>Redirecting you to the login...</div>
})
+OptionalonwithAuthenticationRequired(Profile, {
onRedirecting: () => <div>Redirecting you to the login...</div>
})
Render a message to show that the user is being redirected to the login.
-OptionalreturnwithAuthenticationRequired(Profile, {
returnTo: '/profile'
})
+OptionalreturnwithAuthenticationRequired(Profile, {
returnTo: '/profile'
})
or
@@ -28,4 +28,4 @@Add a path for the onRedirectCallback handler to return the user to after login.
The state of the application before the user was redirected to the login page and any account that the user may have connected to.
-The account that has been connected during the connect flow.
-Union type for all enrollment parameter types
+Union type for all enrollment response types
+Supported MFA factors for enrollment
+ConstThe Auth0 Context
-
Thrown when handling the redirect callback fails, will be one of Auth0's Authentication API's Standard Error Responses: https://auth0.com/docs/api/authentication?javascript#standard-error-responses
-