@auth0/auth0-spa-js

constructor

constructor(options: Auth0ClientOptions);

method checkSession

checkSession: (options?: GetTokenSilentlyOptions) => Promise<void>;

• await auth0.checkSession();

  Check if the user is logged in using getTokenSilently. The difference with getTokenSilently is that this doesn't return a token, but it will pre-fill the token cache.

  This method also heeds the auth0.{clientId}.is.authenticated cookie, as an optimization to prevent calling Auth0 unnecessarily. If the cookie is not present because there was no previous login (or it has expired) then tokens will not be refreshed.

  It should be used for silently logging in the user when you instantiate the Auth0Client constructor. You should not need this if you are using the createAuth0Client factory.

  **Note:** the cookie **may not** be present if running an app using a private tab, as some browsers clear JS cookie data and local storage when the tab or page is closed, or on page reload. This effectively means that checkSession could silently return without authenticating the user on page refresh when using a private tab, despite having previously logged in. As a workaround, use getTokenSilently instead and handle the possible login_required error [as shown in the readme](https://github.com/auth0/auth0-spa-js#creating-the-client).

  Parameter options

method getIdTokenClaims

getIdTokenClaims: () => Promise<IdToken | undefined>;

• const claims = await auth0.getIdTokenClaims();

  Returns all claims from the id_token if available.

method getTokenSilently

getTokenSilently: {
    (
        options: GetTokenSilentlyOptions & { detailedResponse: true }
    ): Promise<GetTokenSilentlyVerboseResponse>;
    (options?: GetTokenSilentlyOptions): Promise<string>;
};

• Fetches a new access token and returns the response from the /oauth/token endpoint, omitting the refresh token.

  Parameter options

• Fetches a new access token and returns it.

  Parameter options

method getTokenWithPopup

getTokenWithPopup: (
    options?: GetTokenWithPopupOptions,
    config?: PopupConfigOptions
) => Promise<string | undefined>;

• const token = await auth0.getTokenWithPopup(options);

  Opens a popup with the /authorize URL using the parameters provided as arguments. Random and secure state and nonce parameters will be auto-generated. If the response is successful, results will be valid according to their expiration times.

  Parameter options

  Parameter config

method getUser

getUser: <TUser extends User>() => Promise<TUser | undefined>;

• const user = await auth0.getUser();

  Returns the user information if available (decoded from the id_token).

method handleRedirectCallback

handleRedirectCallback: <TAppState = any>(
    url?: string
) => Promise<RedirectLoginResult<TAppState>>;

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

method isAuthenticated

isAuthenticated: () => Promise<boolean>;

• const isAuthenticated = await auth0.isAuthenticated();

  Returns true if there's valid information stored, otherwise returns false.

method loginWithPopup

loginWithPopup: (
    options?: PopupLoginOptions,
    config?: PopupConfigOptions
) => Promise<void>;

• try {
   await auth0.loginWithPopup(options);
  } catch(e) {
   if (e instanceof PopupCancelledError) {
     // Popup was closed before login completed
   }
  }

  Opens a popup with the /authorize URL using the parameters provided as arguments. Random and secure state and nonce parameters will be auto-generated. If the response is successful, results will be valid according to their expiration times.

  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.

  Parameter options

  Parameter config

method loginWithRedirect

loginWithRedirect: <TAppState = any>(
    options?: RedirectLoginOptions<TAppState>
) => Promise<void>;

• await auth0.loginWithRedirect(options);

  Performs a redirect to /authorize using the parameters provided as arguments. Random and secure state and nonce parameters will be auto-generated.

  Parameter options

method logout

logout: (options?: LogoutOptions) => Promise<void>;

• await auth0.logout(options);

  Clears the application session and performs a redirect to /v2/logout, using the parameters provided as arguments, to clear the Auth0 session.

  If the federated option is specified it also clears the Identity Provider session. [Read more about how Logout works at Auth0](https://auth0.com/docs/logout).

  Parameter options

constructor

constructor(
    error: string,
    error_description: string,
    state: string,
    appState?: any
);

property appState

appState: any;

property state

state: string;

constructor

constructor(data: CacheKeyData, prefix?: string, suffix?: string);

property audience

audience?: string;

property clientId

clientId: string;

property prefix

prefix: string;

property scope

scope?: string;

property suffix

suffix?: string;

method fromCacheEntry

static fromCacheEntry: (entry: CacheEntry) => CacheKey;

• Utility function to build a CacheKey instance from a cache entry

  Parameter entry

  The entry

  Returns

  An instance of CacheKey

method fromKey

static fromKey: (key: string) => CacheKey;

• Converts a cache key string into a CacheKey instance.

  Parameter key

  The key to convert

  Returns

  An instance of CacheKey

method toKey

toKey: () => string;

• Converts this CacheKey instance into a string for use in a cache

  Returns

  A string representation of the key

constructor

constructor(error: string, error_description: string);

property error

error: string;

property error_description

error_description: string;

method fromPayload

static fromPayload: ({
    error,
    error_description,
}: {
    error: string;
    error_description: string;
}) => GenericError;

property enclosedCache

enclosedCache: ICache;

method allKeys

allKeys: () => string[];

method get

get: <T = Cacheable>(key: string) => MaybePromise<T | undefined>;

method remove

remove: (key: string) => void;

method set

set: <T = Cacheable>(key: string, entry: T) => void;

constructor

constructor(error: string, error_description: string, mfa_token: string);

property mfa_token

mfa_token: string;

constructor

constructor(audience: string, scope: string);

property audience

audience: string;

property scope

scope: string;

constructor

constructor(popup: Window);

property popup

popup: Window;

constructor

constructor(popup: Window);

property popup

popup: Window;

constructor

constructor();

property address

address?: string;

property birthdate

birthdate?: string;

property email

email?: string;

property email_verified

email_verified?: boolean;

property family_name

family_name?: string;

property gender

gender?: string;

property given_name

given_name?: string;

property locale

locale?: string;

property middle_name

middle_name?: string;

property name

name?: string;

property nickname

nickname?: string;

property phone_number

phone_number?: string;

property phone_number_verified

phone_number_verified?: boolean;

property picture

picture?: string;

property preferred_username

preferred_username?: string;

property profile

profile?: string;

property sub

sub?: string;

property updated_at

updated_at?: string;

property website

website?: string;

property zoneinfo

zoneinfo?: string;

property authorizeTimeoutInSeconds

authorizeTimeoutInSeconds?: number;

• A maximum number of seconds to wait before declaring background calls to /authorize as failed for timeout Defaults to 60s.

property cache

cache?: ICache;

• Specify a custom cache implementation to use for token storage and retrieval. This setting takes precedence over cacheLocation if they are both specified.

property cacheLocation

cacheLocation?: CacheLocation;

• The location to use when storing cache data. Valid values are memory or localstorage. The default setting is memory.

  Read more about [changing storage options in the Auth0 docs](https://auth0.com/docs/libraries/auth0-single-page-app-sdk#change-storage-options)

property clientId

clientId: string;

• The Client ID found on your Application settings page

property cookieDomain

cookieDomain?: string;

• The 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.

  To keep a user logged in across multiple subdomains set this to your top-level domain and prefixed with a . (eg: .example.com).

property domain

domain: string;

• Your Auth0 account domain such as 'example.auth0.com', 'example.eu.auth0.com' or , 'example.mycompany.com' (when using [custom domains](https://auth0.com/docs/custom-domains))

property httpTimeoutInSeconds

httpTimeoutInSeconds?: number;

• Specify the timeout for HTTP calls using fetch. The default is 10 seconds.

property issuer

issuer?: string;

• The issuer to be used for validation of JWTs, optionally defaults to the domain above

property leeway

leeway?: number;

• The value in seconds used to account for clock skew in JWT expirations. Typically, this value is no more than a minute or two at maximum. Defaults to 60s.

property legacySameSiteCookie

legacySameSiteCookie?: boolean;

• Sets an additional cookie with no SameSite attribute to support legacy browsers that are not compatible with the latest SameSite changes. This will log a warning on modern browsers, you can disable the warning by setting this to false but be aware that some older useragents will not work, See https://www.chromium.org/updates/same-site/incompatible-clients Defaults to true

property nowProvider

nowProvider?: () => Promise<number> | number;

• Modify the value used as the current time during the token validation.

  **Note**: Using this improperly can potentially compromise the token validation.

property sessionCheckExpiryDays

sessionCheckExpiryDays?: number;

• Number of days until the cookie auth0.is.authenticated will expire Defaults to 1.

property useCookiesForTransactions

useCookiesForTransactions?: boolean;

• If 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 may end up spanning across multiple tabs (e.g. magic links) or you cannot otherwise rely on session storage being available.

property useFormData

useFormData?: boolean;

• If true, data to the token endpoint is transmitted as x-www-form-urlencoded data, if false it will be transmitted as JSON. The default setting is true.

  **Note:** Setting this to false may affect you if you use Auth0 Rules and are sending custom, non-primitive data. If you disable this, please verify that your Auth0 Rules continue to work as intended.

property useRefreshTokens

useRefreshTokens?: boolean;

• If true, refresh tokens are used to fetch new access tokens from the Auth0 server. If false, the legacy technique of using a hidden iframe and the authorization_code grant with prompt=none is used. The default setting is false.

  **Note**: Use of refresh tokens must be enabled by an administrator on your Auth0 client application.

property useRefreshTokensFallback

useRefreshTokensFallback?: boolean;

• If true, fallback to the technique of using a hidden iframe and the authorization_code grant with prompt=none when unable to use refresh tokens. If false, the iframe fallback is not used and errors relating to a failed refresh_token grant should be handled appropriately. The default setting is false.

  **Note**: There might be situations where doing silent auth with a Web Message response from an iframe is not possible, like when you're serving your application from the file system or a custom protocol (like in a Desktop or Native app). In situations like this you can disable the iframe fallback and handle the failed refresh_token grant and prompt the user to login interactively with loginWithRedirect or loginWithPopup."

  E.g. Using the file: protocol in an Electron application does not support that legacy technique.

  Example 1

  let token: string; try { token = await auth0.getTokenSilently(); } catch (e) { if (e.error === 'missing_refresh_token' || e.error === 'invalid_grant') { auth0.loginWithRedirect(); } }

property workerUrl

workerUrl?: string;

• If provided, the SDK will load the token worker from this URL instead of the integrated blob. An example of when this is useful is if you have strict Content-Security-Policy (CSP) and wish to avoid needing to set worker-src: blob:. We recommend either serving the worker, which you can find in the module at <module_path>/dist/auth0-spa-js.worker.production.js, from the same host as your application or using the Auth0 CDN https://cdn.auth0.com/js/auth0-spa-js/<version>/auth0-spa-js.worker.production.js.

  **Note**: The worker is only used when useRefreshTokens: true, cacheLocation: 'memory', and the cache is not custom.

property code

code?: string;

property error

error?: string;

property error_description

error_description?: string;

property state

state: string;

property acr_values

acr_values?: string;

property audience

audience?: string;

• The default audience to be used for requesting API access.

property connection

connection?: string;

• The name of the connection configured for your application. If null, it will redirect to the Auth0 Login Page and show the Login Widget.

property display

display?: 'page' | 'popup' | 'touch' | 'wap';

• - 'page': displays the UI with a full page view - 'popup': displays the UI with a popup window - 'touch': displays the UI in a way that leverages a touch interface - 'wap': displays the UI with a "feature phone" type interface

property id_token_hint

id_token_hint?: string;

• Previously issued ID Token.

property invitation

invitation?: string;

• The Id of an invitation to accept. This is available from the user invitation URL that is given when participating in a user invitation flow.

property login_hint

login_hint?: string;

• The user's email address or other identifier. When your app knows which user is trying to authenticate, you can provide this parameter to pre-fill the email box or select the right session for sign-in.

  This currently only affects the classic Lock experience.

property max_age

max_age?: string | number;

• Maximum allowable elapsed time (in seconds) since authentication. If the last time the user authenticated is greater than this value, the user must be reauthenticated.

property organization

organization?: string;

• The organization to log in to.

  This will specify an organization parameter in your user's login request.

  - If you provide an Organization ID (a string with the prefix org_), it will be validated against the org_id claim of your user's ID Token. The validation is case-sensitive. - If you provide an Organization Name (a string *without* the prefix org_), it will be validated against the org_name claim of your user's ID Token. The validation is case-insensitive.

property prompt

prompt?: 'none' | 'login' | 'consent' | 'select_account';

• - 'none': do not prompt user for login or consent on reauthentication - 'login': prompt user for reauthentication - 'consent': prompt user for consent before processing request - 'select_account': prompt user to select an account

property redirect_uri

redirect_uri?: string;

• The default URL where Auth0 will redirect your browser to with the authentication result. It must be whitelisted in the "Allowed Callback URLs" field in your Auth0 Application's settings. If not provided here, it should be provided in the other methods that provide authentication.

property scope

scope?: string;

• The default scope to be used on authentication requests.

  This defaults to profile email if not set. If you are setting extra scopes and require profile and email to be included then you must include them in the provided scope.

  Note: The openid scope is **always applied** regardless of this setting.

property screen_hint

screen_hint?: 'signup' | 'login' | string;

• Provides a hint to Auth0 as to what flow should be displayed. The default behavior is to show a login page but you can override this by passing 'signup' to show the signup page instead.

  This only affects the New Universal Login Experience.

property ui_locales

ui_locales?: string;

• The space-separated list of language tags, ordered by preference. For example: 'fr-CA fr en'.

index signature

[key: string]: any;

• If you need to send custom parameters to the Authorization Server, make sure to use the original parameter name.

property code_challenge

code_challenge: string;

property code_challenge_method

code_challenge_method: string;

property nonce

nonce: string;

property redirect_uri

redirect_uri?: string;

property response_mode

response_mode: string;

property response_type

response_type: string;

property scope

scope: string;

property state

state: string;

property claims

claims: IdToken;

property user

user: User;

property authorizationParams

authorizationParams?: {
    /**
     * There's no actual redirect when getting a token silently,
     * but, according to the spec, a `redirect_uri` param is required.
     * Auth0 uses this parameter to validate that the current `origin`
     * matches the `redirect_uri` `origin` when sending the response.
     * It must be whitelisted in the "Allowed Web Origins" in your
     * Auth0 Application's settings.
     */
    redirect_uri?: string;
    /**
     * The scope that was used in the authentication request
     */
    scope?: string;
    /**
     * The audience that was used in the authentication request
     */
    audience?: string;
    /**
     * If you need to send custom parameters to the Authorization Server,
     * make sure to use the original parameter name.
     */
    [key: string]: any;
};

• Parameters that will be sent back to Auth0 as part of a request.

property cacheMode

cacheMode?: 'on' | 'off' | 'cache-only';

• When off, ignores the cache and always sends a request to Auth0. When cache-only, only reads from the cache and never sends a request to Auth0. Defaults to on, where it both reads from the cache and sends a request to Auth0 as needed.

property detailedResponse

detailedResponse?: boolean;

• If true, the full response from the /oauth/token endpoint (or the cache, if the cache was used) is returned (minus refresh_token if one was issued). Otherwise, just the access token is returned.

  The default is false.

property timeoutInSeconds

timeoutInSeconds?: number;

• A maximum number of seconds to wait before declaring the background /authorize call as failed for timeout Defaults to 60s.

property cacheMode

cacheMode?: 'on' | 'off' | 'cache-only';

• When off, ignores the cache and always sends a request to Auth0. When cache-only, only reads from the cache and never sends a request to Auth0. Defaults to on, where it both reads from the cache and sends a request to Auth0 as needed.

method allKeys

allKeys: () => MaybePromise<string[]>;

method get

get: <T = Cacheable>(key: string) => MaybePromise<T | undefined>;

method remove

remove: (key: string) => MaybePromise<void>;

method set

set: <T = Cacheable>(key: string, entry: T) => MaybePromise<void>;

property acr

acr?: string;

property address

address?: string;

property amr

amr?: string[];

property at_hash

at_hash?: string;

property aud

aud?: string;

property auth_time

auth_time?: string;

property azp

azp?: string;

property birthdate

birthdate?: string;

property c_hash

c_hash?: string;

property cnf

cnf?: string;

property email

email?: string;

property email_verified

email_verified?: boolean;

property exp

exp?: number;

property family_name

family_name?: string;

property gender

gender?: string;

property given_name

given_name?: string;

property iat

iat?: number;

property iss

iss?: string;

property jti

jti?: string;

property locale

locale?: string;

property middle_name

middle_name?: string;

property name

name?: string;

property nbf

nbf?: number;

property nickname

nickname?: string;

property nonce

nonce?: string;

property org_id

org_id?: string;

property org_name

org_name?: string;

property phone_number

phone_number?: string;

property phone_number_verified

phone_number_verified?: boolean;

property picture

picture?: string;

property preferred_username

preferred_username?: string;

property profile

profile?: string;

property sid

sid?: string;

property sub_jwk

sub_jwk?: string;

property updated_at

updated_at?: string;

property website

website?: string;

property zoneinfo

zoneinfo?: string;

index signature

[key: string]: any;

property aud

aud: string;

property id_token

id_token: string;

property iss

iss: string;

property leeway

leeway?: number;

property max_age

max_age?: number;

property nonce

nonce?: string;

property now

now?: number;

property organization

organization?: string;

property onRedirect

onRedirect?: (url: string) => Promise<void>;

• Used to control the redirect and not rely on the SDK to do the actual redirect.

  Example 1

  await auth0.logout({ async onRedirect(url) { window.location.replace(url); } });

  Deprecated

  since v2.0.1, use openUrl instead.

property openUrl

openUrl?: false | ((url: string) => Promise<void> | void);

• Used to control the redirect and not rely on the SDK to do the actual redirect.

  Set to false to disable the redirect, or provide a function to handle the actual redirect yourself.

  Example 1

  await auth0.logout({ openUrl(url) { window.location.replace(url); } });

  Example 2

  import { Browser } from '@capacitor/browser';

  await auth0.logout({ async openUrl(url) { await Browser.open({ url }); } });

property clientId

clientId?: string | null;

• The clientId of your application.

  If this property is not set, then the clientId that was used during initialization of the SDK is sent to the logout endpoint.

  If this property is set to null, then no client ID value is sent to the logout endpoint.

  [Read more about how redirecting after logout works](https://auth0.com/docs/logout/guides/redirect-users-after-logout)

property logoutParams

logoutParams?: {
    /**
     * When supported by the upstream identity provider,
     * forces the user to logout of their identity provider
     * and from Auth0.
     * [Read more about how federated logout works at Auth0](https://auth0.com/docs/logout/guides/logout-idps)
     */
    federated?: boolean;
    /**
     * The URL where Auth0 will redirect your browser to after the logout.
     *
     * **Note**: If the `client_id` parameter is included, the
     * `returnTo` URL that is provided must be listed in the
     * Application's "Allowed Logout URLs" in the Auth0 dashboard.
     * However, if the `client_id` parameter is not included, the
     * `returnTo` URL must be listed in the "Allowed Logout URLs" at
     * the account level in the Auth0 dashboard.
     *
     * [Read more about how redirecting after logout works](https://auth0.com/docs/logout/guides/redirect-users-after-logout)
     */
    returnTo?: string;
    /**
     * If you need to send custom parameters to the logout endpoint, make sure to use the original parameter name.
     */
    [key: string]: any;
};

• Parameters to pass to the logout endpoint. This can be known parameters defined by Auth0 or custom parameters you wish to provide.

property audience

audience: string;

property code

code: string;

property code_verifier

code_verifier: string;

property redirect_uri

redirect_uri: string;

property scope

scope: string;

property popup

popup?: any;

• Accepts an already-created popup window to use. If not specified, the SDK will create its own. This may be useful for platforms like iOS that have security restrictions around when popups can be invoked (e.g. from a user click event)

property timeoutInSeconds

timeoutInSeconds?: number;

• The number of seconds to wait for a popup response before throwing a timeout error. Defaults to 60s

property appState

appState?: TAppState;

• Used to store state before doing the redirect

property fragment

fragment?: string;

• Used to add to the URL fragment before redirecting

property onRedirect

onRedirect?: (url: string) => Promise<void>;

• Used to control the redirect and not rely on the SDK to do the actual redirect.

  Example 1

  const client = new Auth0Client({ async onRedirect(url) { window.location.replace(url); } });

  Deprecated

  since v2.0.1, use openUrl instead.

property openUrl

openUrl?: (url: string) => Promise<void> | void;

• Used to control the redirect and not rely on the SDK to do the actual redirect.

  Example 1

  const client = new Auth0Client({ openUrl(url) { window.location.replace(url); } });

  Example 2

  import { Browser } from '@capacitor/browser';

  const client = new Auth0Client({ async openUrl(url) { await Browser.open({ url }); } });

property appState

appState?: TAppState;

• State stored when the redirect request was made

property refresh_token

refresh_token: string;

property auth0Client

auth0Client: any;

property baseUrl

baseUrl: string;

property client_id

client_id: string;

property grant_type

grant_type: string;

property timeout

timeout?: number;

property useFormData

useFormData?: boolean;

index signature

[key: string]: any;