@okta/okta-auth-js 5.4.3 → 5.8.0

package/README.md

@@ -343,10 +343,9 @@ Depending on your preferences it is possible to use the following callback strat
 #### Handling the callback with hash routing
 
 According to the OAuth 2.0 spec the redirect URI "MUST NOT contain a fragment component": <https://tools.ietf.org/html/rfc6749#section-3.1.2>
-So in case of using hash-based `#` strategy and OAuth 2.0, the redirect URI can be defined only like a base url, without any specific route.
-That's mean that hash-based router will receive the redirect callback on the main / default route. So we recommend to define the logic that will parse redirect url at the very beginning of your app. So the flow will be similar to [Handling the callback without routing](#handling-the-callback-without-routing)
+When using a hash/fragment routing strategy and OAuth 2.0, the redirect callback will be the main / default route. The redirect callback flow will be very similar to [handling the callback without routing](#handling-the-callback-without-routing). We recommend defining the logic that will parse redirect url at the very beginning of your app, before any other authorization checks.
 
-Additionally if using hash routing, we recommend to use PKCE and responseMode query (which is the default for PKCE). Using implicit flow, with tokens in the hash could cause unpredictable results since hash routers like to rewrite the fragment.
+Additionally, if using hash routing, we recommend using PKCE and responseMode "query" (this is the default for PKCE). With implicit flow, tokens in the hash could cause unpredictable results since hash routers may rewrite the fragment.
 
 #### Handling the callback with path routing (on a dedicated route)
 
@@ -429,11 +428,11 @@ Default value is `true` which enables the [PKCE OAuth Flow](#pkce-oauth-20-flow)
 
 #### responseMode
 
-When requesting tokens using [token.getWithRedirect](#tokengetwithredirectoptions) values will be returned as parameters appended to the [redirectUri](#additional-options).
+When requesting tokens using [token.getWithRedirect](#tokengetwithredirectoptions) values will be returned as parameters appended to the [redirectUri](#configuration-options).
 
 In most cases you will not need to set a value for `responseMode`. Defaults are set according to the [OpenID Connect 1.0 specification](https://openid.net/specs/openid-connect-core-1_0.html#Authentication).
 
-* For [PKCE OAuth Flow](#pkce-oauth-20-flow)), the authorization code will be in search query of the URL. Clients using the PKCE flow can opt to instead receive the authorization code in the hash fragment by setting the [responseMode](#additional-options) option to "fragment".
+* For [PKCE OAuth Flow](#pkce-oauth-20-flow)), the authorization code will be in search query of the URL. Clients using the PKCE flow can opt to instead receive the authorization code in the hash fragment by setting the [responseMode](#configuration-options) option to "fragment".
 
 * For [Implicit OAuth Flow](#implicit-oauth-20-flow)), tokens will be in the hash fragment of the URL. This cannot be changed.
 
@@ -463,6 +462,11 @@ ID token signatures are validated by default when `token.getWithoutPrompt`, `tok
 
 Defaults to 300 (five minutes). This is the maximum difference allowed between a client's clock and Okta's, in seconds, when validating tokens. Setting this to 0 is not recommended, because it increases the likelihood that valid tokens will fail validation.
 
+#### `ignoreLifetime`
+
+Token lifetimes are validated using the `maxClockSkew`.
+To override this and disable token lifetime validation, set this value to `true`. 
+
 #### `transformAuthState`
 
 Callback function. When [updateAuthState](#authstatemanagerupdateauthstate) is called a new authState object is produced. Providing a `transformAuthState` function allows you to modify or replace this object before it is stored and emitted. A common use case is to change the meaning of [isAuthenticated](#authstatemanager). By default, `updateAuthState` will set `authState.isAuthenticated` to true if unexpired tokens are available from [tokenManager](#tokenmanager). This logic could be customized to also require a valid Okta SSO session:
@@ -508,7 +512,11 @@ const config = {
 
 const oktaAuth = new OktaAuth(config);
 if (oktaAuth.isLoginRedirect()) {
-  oktaAuth.handleLoginRedirect();
+  try {
+    await oktaAuth.handleLoginRedirect();
+  } catch (e) {
+    // log or display error details
+  }
 }
 ```
 
@@ -815,24 +823,14 @@ Defaults to `none` if the `secure` option is `true`, or `lax` if the `secure` op
 * [getAccessToken](#getaccesstoken)
 * [storeTokensFromRedirect](#storetokensfromredirect)
 * [setOriginalUri](#setoriginaluriuri)
-* [getOriginalUri](#getoriginaluri)
+* [getOriginalUri](#getoriginaluristate)
 * [removeOriginalUri](#removeoriginaluri)
 * [isLoginRedirect](#isloginredirect)
 * [handleLoginRedirect](#handleloginredirecttokens)
+* [setHeaders](#setheaders)
 * [tx.resume](#txresume)
 * [tx.exists](#txexists)
 * [transaction.status](#transactionstatus)
-  * [LOCKED_OUT](#locked_out)
-  * [PASSWORD_EXPIRED](#password_expired)
-  * [PASSWORD_RESET](#password_reset)
-  * [PASSWORD_WARN](#password_warn)
-  * [RECOVERY](#recovery)
-  * [RECOVERY_CHALLENGE](#recovery_challenge)
-  * [MFA_ENROLL](#mfa_enroll)
-  * [MFA_ENROLL_ACTIVATE](#mfa_enroll_activate)
-  * [MFA_REQUIRED](#mfa_required)
-  * [MFA_CHALLENGE](#mfa_challenge)
-  * [SUCCESS](#success)
 * [session](#session)
   * [session.setCookieAndRedirect](#sessionsetcookieandredirectsessiontoken-redirecturi)
   * [session.exists](#sessionexists)
@@ -885,41 +883,23 @@ Starts the `OktaAuth` service. See [running as a service](#running-as-a-service)
 
 ### `signInWithCredentials(options)`
 
-> :hourglass: async
-
-The goal of this authentication flow is to [set an Okta session cookie on the user's browser](https://developer.okta.com/use_cases/authentication/session_cookie#retrieving-a-session-cookie-by-visiting-a-session-redirect-link) or [retrieve an `id_token` or `access_token`](https://developer.okta.com/use_cases/authentication/session_cookie#retrieving-a-session-cookie-via-openid-connect-authorization-endpoint). The flow is started using `signInWithCredentials`.
-
-* `username` - User’s non-qualified short-name (e.g. dade.murphy) or unique fully-qualified login (e.g dade.murphy@example.com)
-* `password` - The password of the user
-* `sendFingerprint` - Enabling this will send a `X-Device-Fingerprint` header. Defaults to `false`. See [Primary authentication with device fingerprint](https://developer.okta.com/docs/reference/api/authn/#primary-authentication-with-device-fingerprinting) for more information on the `X-Device-Fingerprint` header.
-
-```javascript
-authClient.signInWithCredentials({
-  username: 'some-username',
-  password: 'some-password'
-})
-.then(function(transaction) {
-  if (transaction.status === 'SUCCESS') {
-    authClient.session.setCookieAndRedirect(transaction.sessionToken); // Sets a cookie on redirect
-  } else {
-    throw 'We cannot handle the ' + transaction.status + ' status';
-  }
-})
-.catch(function(err) {
-  console.error(err);
-});
-```
+See [authn API](docs/authn.md#signinwithcredentials).
 
 ### `signInWithRedirect(options)`
 
 > :link: web browser only <br>
+> :hourglass: async
 
 Starts the full-page redirect to Okta with [optional request parameters](#authorize-options). In this flow, there is a originalUri parameter in options to track the route before the user signIn, and the addtional params are mapped to the [Authorize options](#authorize-options).
-You can use [storeTokensFromRedirect](#storetokensfromredirect) to store tokens and [getOriginalUri](#getoriginaluri) to clear the intermediate state (the originalUri) after successful authentication.
+You can use [storeTokensFromRedirect](#storetokensfromredirect) to store tokens and [getOriginalUri](#getoriginaluristate) to clear the intermediate state (the originalUri) after successful authentication.
 
 ```javascript
 if (authClient.isLoginRedirect()) {
-  await authClient.handleLoginRedirect();
+  try {
+    await authClient.handleLoginRedirect();
+  } catch (e) {
+    // log or display error details
+  }
 } else if (!await authClient.isAuthenticated()) {
   // Start the browser based oidc flow, then parse tokens from the redirect callback url
   authClient.signInWithRedirect();
@@ -1016,91 +996,15 @@ Revokes the refresh token (if any) for this application so it can no longer be u
 
 ### `forgotPassword(options)`
 
-> :hourglass: async
-
-Starts a [new password recovery transaction](https://developer.okta.com/docs/api/resources/authn#forgot-password) for a given user and issues a recovery token that can be used to reset a user’s password.
-
-* `username` - User’s non-qualified short-name (e.g. dade.murphy) or unique fully-qualified login (e.g dade.murphy@example.com)
-* `factorType` - Recovery factor to use for primary authentication. Supported options are `SMS`, `EMAIL`, or `CALL`
-* `relayState` - Optional state value that is persisted for the lifetime of the recovery transaction
-
-```javascript
-authClient.forgotPassword({
-  username: 'dade.murphy@example.com',
-  factorType: 'SMS',
-})
-.then(function(transaction) {
-  return transaction.verify({
-    passCode: '123456' // The passCode from the SMS or CALL
-  });
-})
-.then(function(transaction) {
-  if (transaction.status === 'SUCCESS') {
-    authClient.session.setCookieAndRedirect(transaction.sessionToken);
-  } else {
-    throw 'We cannot handle the ' + transaction.status + ' status';
-  }
-})
-.catch(function(err) {
-  console.error(err);
-});
-```
+See [authn API](docs/authn.md#forgotpasswordoptions).
 
 ### `unlockAccount(options)`
 
-> :hourglass: async
-
-Starts a [new unlock recovery transaction](https://developer.okta.com/docs/api/resources/authn#unlock-account) for a given user and issues a recovery token that can be used to unlock a user’s account.
-
-* `username` - User’s non-qualified short-name (e.g. dade.murphy) or unique fully-qualified login (e.g dade.murphy@example.com)
-* `factorType` - Recovery factor to use for primary authentication. Supported options are `SMS`, `EMAIL`, or `CALL`
-* `relayState` - Optional state value that is persisted for the lifetime of the recovery transaction
-
-```javascript
-authClient.unlockAccount({
-  username: 'dade.murphy@example.com',
-  factorType: 'SMS',
-})
-.then(function(transaction) {
-  return transaction.verify({
-    passCode: '123456' // The passCode from the SMS
-  });
-})
-.then(function(transaction) {
-  if (transaction.status === 'SUCCESS') {
-    authClient.session.setCookieAndRedirect(transaction.sessionToken);
-  } else {
-    throw 'We cannot handle the ' + transaction.status + ' status';
-  }
-})
-.catch(function(err) {
-  console.error(err);
-});
-```
+See [authn API](docs/authn.md#unlockaccountoptions).
 
 ### `verifyRecoveryToken(options)`
 
-> :hourglass: async
-
-Validates a recovery token that was distributed to the end-user to continue the [recovery transaction](https://developer.okta.com/docs/api/resources/authn#verify-recovery-token).
-
-* `recoveryToken` - Recovery token that was distributed to end-user via an out-of-band mechanism such as email
-
-```javascript
-authClient.verifyRecoveryToken({
-  recoveryToken: '00xdqXOE5qDZX8-PBR1bYv8AESqIFinDy3yul01tyh'
-})
-.then(function(transaction) {
-  if (transaction.status === 'SUCCESS') {
-    authClient.session.setCookieAndRedirect(transaction.sessionToken);
-  } else {
-    throw 'We cannot handle the ' + transaction.status + ' status';
-  }
-})
-.catch(function(err) {
-  console.error(err);
-});
-```
+See [authn API](docs/authn.md#verifyrecoverytokenoptions).
 
 ### `webfinger(options)`
 
@@ -1170,11 +1074,11 @@ Parses tokens from the redirect url and stores them.
 
 ### `setOriginalUri(uri?)`
 
-Stores the current URL state before a redirect occurs. By default it stores `window.location.href`.
+Stores the current URL state before a redirect occurs.
 
-### `getOriginalUri()`
+### `getOriginalUri(state?)`
 
-Returns the stored URI string stored by [setOriginal](#setoriginaluriuri). By default it returns `window.location.origin`.
+Returns the stored URI string stored by [setOriginal](#setoriginaluriuri). An OAuth `state` parameter is optional. If no value is passed for `state`, the URI is retrieved from isolated session storage and will work in a single browser. If a valid OAuth `state` is passed this method can return the URI stored from another browser tab.
 
 ### `removeOriginalUri()`
 
@@ -1189,886 +1093,67 @@ Check `window.location` to verify if the app is in OAuth callback state or not.
 ```javascript
 if (authClient.isLoginRedirect()) {
   // callback flow
-  await authClient.handleLoginRedirect();
+  try {
+    await authClient.handleLoginRedirect();
+  } catch (e) {
+    // log or display error details
+  }
 } else {
   // normal app flow
 }
 ```
 
-### `handleLoginRedirect(tokens?)`
+### `handleLoginRedirect(tokens?, originalUri?)`
 
 > :link: web browser only <br>
-
-Stores passed in tokens or tokens from redirect url into storage, then redirect users back to the [originalUri](#setoriginaluriuri). By default it calls `window.location.replace` for the redirection. The default behavior can be overrided by providing [options.restoreOriginalUri](#additional-options).
-
-### `tx.resume()`
-
-> :hourglass: async
-
-Resumes an in-progress **transaction**. This is useful if a user navigates away from the login page before authentication is complete.
-
-```javascript
-var exists = authClient.tx.exists();
-if (exists) {
-  authClient.tx.resume()
-  .then(function(transaction) {
-    console.log('current status:', transaction.status);
-  })
-  .catch(function(err) {
-    console.error(err);
-  });
-}
-```
-
-### `tx.exists()`
-
-Check for a **transaction** to be resumed. This is synchronous and returns `true` or `false`.
-
-```javascript
-var exists = authClient.tx.exists();
-if (exists) {
-  console.log('a session exists');
-} else {
-  console.log('a session does not exist');
-}
-```
-
-### `transaction.status`
-
-> :hourglass: async
-
-When Auth Client methods resolve, they return a **transaction** object that encapsulates [the new state in the authentication flow](https://developer.okta.com/docs/reference/api/authn/#transaction-state). This **transaction** contains metadata about the current state, and methods that can be used to progress to the next state.
-
-![State Model Diagram](https://developer.okta.com/img/auth-state-model.png "State Model Diagram")
-
-#### Common methods
-
-##### `cancel()`
-
 > :hourglass: async
-Terminates the current auth flow.
-
-```javascript
-transaction.cancel()
-.then(function() {
-  // transaction canceled. You can now start another with authClient.signIn
-});
-```
-
-##### `changePassword(options)`
-
-[Changes](https://developer.okta.com/docs/api/resources/authn#reset-password) a user's password.
-
-* `oldPassword` - User’s current password that is expired
-* `newPassword` - New password for user
-
-```javascript
-transaction.changePassword({
-  oldPassword: '0ldP4ssw0rd',
-  newPassword: 'N3wP4ssw0rd'
-});
-```
-
-##### `resetPassword(options)`
-
-[Reset](https://developer.okta.com/docs/api/resources/authn#reset-password) a user's password.
-
-* `newPassword` - New password for user
-
-```javascript
-transaction.resetPassword({
-  newPassword: 'N3wP4ssw0rd'
-});
-```
-
-##### `skip()`
-
-Ignore the warning and continue.
-
-```javascript
-transaction.skip();
-```
-
-#### LOCKED_OUT
-
-The user account is [locked](https://developer.okta.com/docs/api/resources/authn#show-lockout-failures); self-service unlock or admin unlock is required.
-
-<details>
-  <summary><b>Example Response</b></summary>
-
-  ```javascript
-  {
-    status: 'LOCKED_OUT',
-    unlock: function(options) { /* returns another transaction */ },
-    cancel: function() { /* terminates the auth flow */ },
-    data: { /* the parsed json response */ }
-  }
-  ```
-
-</details>
-
-##### `unlock(options)`
-
-[Unlock](https://developer.okta.com/docs/api/resources/authn#unlock-account) the user account.
-
-* `username` - User’s non-qualified short-name (e.g. dade.murphy) or unique fully-qualified login (e.g dade.murphy@example.com)
-* `factorType` - Recovery factor to use for primary authentication. Supported options are `SMS`, `EMAIL`, or `CALL`
-* `relayState` - Optional state value that is persisted for the lifetime of the recovery transaction
 
-```javascript
-transaction.unlock({
-  username: 'dade.murphy@example.com',
-  factorType: 'EMAIL'
-});
-```
-
-#### PASSWORD_EXPIRED
-
-The user’s password was successfully validated but is [expired](https://developer.okta.com/docs/api/resources/authn#response-example-expired-password).
-
-<details>
-  <summary><b>Example Response</b></summary>
-
-  ```javascript
-  {
-    status: 'PASSWORD_EXPIRED',
-    expiresAt: '2014-11-02T23:39:03.319Z',
-    user: {
-      id: '00ub0oNGTSWTBKOLGLNR',
-      profile: {
-        login: 'isaac@example.org',
-        firstName: 'Isaac',
-        lastName: 'Brock',
-        locale: 'en_US',
-        timeZone: 'America/Los_Angeles'
-      }
-    },
-    changePassword: function(options) { /* returns another transaction */ },
-    cancel: function() { /* terminates the auth flow */ },
-    data: { /* the parsed json response */ }
-  }
-  ```
-
-</details>
-
-#### PASSWORD_RESET
-
-The user successfully answered their recovery question and can set a new password.
-
-<details>
-  <summary><b>Example Response</b></summary>
-
-  ```javascript
-  {
-    status: 'PASSWORD_EXPIRED',
-    expiresAt: '2014-11-02T23:39:03.319Z',
-    user: {
-      id: '00ub0oNGTSWTBKOLGLNR',
-      profile: {
-        login: 'isaac@example.org',
-        firstName: 'Isaac',
-        lastName: 'Brock',
-        locale: 'en_US',
-        timeZone: 'America/Los_Angeles'
-      }
-    },
-    resetPassword: function(options) { /* returns another transaction */ },
-    cancel: function() { /* terminates the auth flow */ },
-    data: { /* the parsed json response */ }
-  }
-```
+Stores passed in tokens or tokens from redirect url into storage, then redirect users back to the [originalUri](#setoriginaluriuri). When using `PKCE` authorization code flow, this method also exchanges authorization code for tokens. By default it calls `window.location.replace` for the redirection. The default behavior can be overrided by providing [options.restoreOriginalUri](#configuration-options). By default, [originalUri](#getoriginaluristate) will be retrieved from storage, but this can be overridden by passing a value fro `originalUri` to this function in the 2nd parameter.
 
-</details>
+> **Note:** `handleLoginRedirect` throws `OAuthError` or `AuthSdkError` in case there are errors during token retrieval.
 
-#### PASSWORD_WARN
+### `setHeaders()`
 
-The user’s password was successfully validated but is about to expire and should be changed.
-
-<details>
-  <summary><b>Example Response</b></summary>
-
-  ```javascript
-  {
-    status: 'PASSWORD_WARN',
-    expiresAt: '2014-11-02T23:39:03.319Z',
-    user: {
-      id: '00ub0oNGTSWTBKOLGLNR',
-      profile: {
-        login: 'isaac@example.org',
-        firstName: 'Isaac',
-        lastName: 'Brock',
-        locale: 'en_US',
-        timeZone: 'America/Los_Angeles'
-      }
-    },
-    policy: {
-      expiration:{
-        passwordExpireDays: 0
-      },
-      complexity: {
-        minLength: 8,
-        minLowerCase: 1,
-        minUpperCase: 1,
-        minNumber: 1,
-        minSymbol: 0,
-        excludeUsername: true
-      },
-      age:{
-        minAgeMinutes:0,
-        historyCount:0
-      }
-    },
-    changePassword: function(options) { /* returns another transaction */ },
-    skip: function() { /* returns another transaction */ },
-    cancel: function() { /* terminates the auth flow */ },
-    data: { /* the parsed json response */ }
-  }
-  ```
-
-</details>
-
-#### RECOVERY
-
-The user has requested a recovery token to reset their password or unlock their account.
-
-<details>
-  <summary><b>Example Response</b></summary>
-
-  ```javascript
-  {
-    status: 'RECOVERY',
-    expiresAt: '2014-11-02T23:39:03.319Z',
-    recoveryType: 'PASSWORD', // or 'UNLOCK'
-    user: {
-      id: '00ub0oNGTSWTBKOLGLNR',
-      profile: {
-        login: 'isaac@example.org',
-        firstName: 'Isaac',
-        lastName: 'Brock',
-        locale: 'en_US',
-        timeZone: 'America/Los_Angeles'
-      },
-      recovery_question: {
-        question: "Who's a major player in the cowboy scene?"
-      }
-    },
-    answer: function(options) { /* returns another transaction */ },
-    recovery: function(options) { /* returns another transaction */ },
-    cancel: function() { /* terminates the auth flow */ },
-    data: { /* the parsed json response */ }
-  }
-  ```
-
-</details>
-
-##### `answer(options)`
-
-* `answer` - [Answer](https://developer.okta.com/docs/api/resources/authn#answer-recovery-question) to user’s recovery question
+Can set (or unset) request headers after construction.
 
 ```javascript
-transaction.answer({
-  answer: 'My favorite recovery question answer'
-});
-```
-
-##### `recovery(options)`
-
-* `recoveryToken` - [Recovery](https://developer.okta.com/docs/api/resources/authn#verify-recovery-token) token that was distributed to end-user via out-of-band mechanism such as email
-
-```javascript
-transaction.recovery({
-  recoveryToken: '00xdqXOE5qDZX8-PBR1bYv8AESqIFinDy3yul01tyh'
-});
-```
-
-#### RECOVERY_CHALLENGE
-
-The user must verify the factor-specific recovery challenge.
-
-<details>
-  <summary><b>Example Response</b></summary>
-
-  ```javascript
-  {
-    status: 'RECOVERY_CHALLENGE',
-    expiresAt: '2014-11-02T23:39:03.319Z',
-    recoveryType: 'PASSWORD', // or 'UNLOCK',
-    factorType: 'EMAIL', // or 'SMS'
-    user: {
-      id: '00ub0oNGTSWTBKOLGLNR',
-      profile: {
-        login: 'isaac@example.org',
-        firstName: 'Isaac',
-        lastName: 'Brock',
-        locale: 'en_US',
-        timeZone: 'America/Los_Angeles'
-      }
-    },
-    verify: function(options) { /* returns another transaction */ },
-    resend: function() { /* returns another transaction */ },
-    cancel: function() { /* terminates the auth flow */ },
-    data: { /* the parsed json response */ }
-  }
-  ```
-
-</details>
-
-##### `verify(options)`
-
-* `passCode` - OTP sent to device for [verification](https://developer.okta.com/docs/api/resources/authn#verify-sms-recovery-factor)
-
-```javascript
-transaction.verify({
-  passCode: '615243'
-});
-```
-
-##### `resend()`
-
-[Resend](https://developer.okta.com/docs/api/resources/authn#resend-sms-recovery-challenge) the recovery email or text.
-
-```javascript
-transaction.resend();
-```
-
-#### MFA_ENROLL
-
-When MFA is required, but a user isn’t enrolled in MFA, they must enroll in at least one factor.
-
-<details>
-  <summary><b>Example Response</b></summary>
-
-  ```javascript
-  {
-    status: 'MFA_ENROLL',
-    expiresAt: '2014-11-02T23:39:03.319Z',
-    user: {
-      id: '00ub0oNGTSWTBKOLGLNR',
-      profile: {
-        login: 'isaac@example.org',
-        firstName: 'Isaac',
-        lastName: 'Brock',
-        locale: 'en_US',
-        timeZone: 'America/Los_Angeles'
-      }
-    },
-    factors: [{
-      provider: 'OKTA',
-      factorType: 'question',
-      questions: function() { /* returns an array of possible questions */ },
-      enroll: function(options) { /* returns another transaction */ }
-    }, {
-      provider: 'OKTA',
-      factorType: 'sms',
-      enroll: function(options) { /* returns another transaction */ }
-    }, {
-      provider: 'OKTA',
-      factorType: 'call',
-      enroll: function(options) { /* returns another transaction */ }
-    }, {
-      provider: 'OKTA',
-      factorType: 'push',
-      enroll: function(options) { /* returns another transaction */ }
-    }, {
-      provider: 'OKTA',
-      factorType: 'token:software:totp',
-      enroll: function(options) { /* returns another transaction */ }
-    }, {
-      provider: 'GOOGLE',
-      factorType: 'token:software:totp',
-      enroll: function(options) { /* returns another transaction */ }
-    }, {
-      provider: 'YUBICO',
-      factorType: 'token:hardware',
-      enroll: function(options) { /* returns another transaction */ }
-    }, {
-      provider: 'RSA',
-      factorType: 'token',
-      enroll: function(options) { /* returns another transaction */ }
-    }, {
-      provider: 'SYMANTEC',
-      factorType: 'token',
-      enroll: function(options) { /* returns another transaction */ }
-    }],
-    cancel: function() { /* terminates the auth flow */ },
-    data: { /* the parsed json response */ }
-  }
-  ```
-
-</details>
-
-To enroll in a factor, select one from the factors array, then use the following methods.
-
-```javascript
-var factor = transaction.factors[/* index of the desired factor */];
-```
-
-##### `questions()`
-
-List the available [questions](https://developer.okta.com/docs/api/resources/factors#list-security-questions) for the question factorType.
-
-```javascript
-var questionFactor = transaction.factors.find(function(factor) {
-  return factor.provider === 'OKTA' && factor.factorType === 'question';
-});
-
-questionFactor.questions()
-.then(function(questions) {
-  // Display questions for the user to select from
-});
-```
-
-##### `enroll(options)`
-
-The enroll options depend on the desired factor.
-
-###### [OKTA question](https://developer.okta.com/docs/api/resources/factors#enroll-okta-security-question-factor)
-
-```javascript
-var questionFactor = transaction.factors.find(function(factor) {
-  return factor.provider === 'OKTA' && factor.factorType === 'question';
-});
-
-questionFactor.enroll({
-  profile: {
-    question: 'disliked_food', // all questions available using questionFactor.questions()
-    answer: 'mayonnaise'
-  }
-});
-```
-
-###### [OKTA sms](https://developer.okta.com/docs/api/resources/factors#enroll-okta-sms-factor)
-
-```javascript
-var factor = transaction.factors.find(function(factor) {
-  return factor.provider === 'OKTA' && factor.factorType === 'sms';
-});
-
-factor.enroll({
-  profile: {
-    phoneNumber: '+1-555-415-1337',
-    updatePhone: true
-  }
-});
-
-// The passCode sent to the phone is verified in MFA_ENROLL_ACTIVATE
-```
-
-###### [OKTA call](https://developer.okta.com/docs/api/resources/factors#enroll-okta-call-factor)
-
-```javascript
-var factor = transaction.factors.find(function(factor) {
-  return factor.provider === 'OKTA' && factor.factorType === 'call';
-});
-
-factor.enroll({
-  profile: {
-    phoneNumber: '+1-555-415-1337',
-    updatePhone: true
-  }
-});
-
-// The passCode from the call is verified in MFA_ENROLL_ACTIVATE
-```
-
-###### [OKTA push](https://developer.okta.com/docs/api/resources/factors#enroll-okta-verify-push-factor)
-
-```javascript
-var factor = transaction.factors.find(function(factor) {
-  return factor.provider === 'OKTA' && factor.factorType === 'push';
-});
-
-factor.enroll();
-
-// The phone will need to scan a QR Code in MFA_ENROLL_ACTIVATE
-```
-
-###### [OKTA token:software:totp](https://developer.okta.com/docs/api/resources/factors#enroll-okta-verify-totp-factor)
-
-```javascript
-var factor = transaction.factors.find(function(factor) {
-  return factor.provider === 'OKTA' && factor.factorType === 'token:software:totp';
-});
-
-factor.enroll();
-
-// The phone will need to scan a QR Code in MFA_ENROLL_ACTIVATE
-```
-
-###### [GOOGLE token:software:totp](https://developer.okta.com/docs/api/resources/factors#enroll-google-authenticator-factor)
-
-```javascript
-var factor = transaction.factors.find(function(factor) {
-  return factor.provider === 'GOOGLE' && factor.factorType === 'token:software:totp';
-});
-
-factor.enroll();
-
-// The phone will need to scan a QR Code in MFA_ENROLL_ACTIVATE
-```
-
-###### [YUBICO token:hardware](https://developer.okta.com/docs/api/resources/factors#enroll-yubikey-factor)
-
-```javascript
-var factor = transaction.factors.find(function(factor) {
-  return factor.provider === 'YUBICO' && factor.factorType === 'token:hardware';
-});
-
-factor.enroll({
-  passCode: 'cccccceukngdfgkukfctkcvfidnetljjiknckkcjulji'
-});
-```
-
-###### [RSA token](https://developer.okta.com/docs/api/resources/factors#enroll-rsa-securid-factor)
-
-```javascript
-var factor = transaction.factors.find(function(factor) {
-  return factor.provider === 'RSA' && factor.factorType === 'token';
-});
-
-factor.enroll({
-  passCode: '5275875498',
-  profile: {
-    credentialId: 'dade.murphy@example.com'
-  }
-});
-```
-
-###### [SYMANTEC token](https://developer.okta.com/docs/api/resources/factors#enroll-symantec-vip-factor)
-
-```javascript
-var factor = transaction.factors.find(function(factor) {
-  return factor.provider === 'SYMANTEC' && factor.factorType === 'token';
-});
-
-factor.enroll({
-  passCode: '875498',
-  nextPassCode: '678195',
-  profile: {
-    credentialId: 'VSMT14393584'
-  }
-});
-```
-
-#### MFA_ENROLL_ACTIVATE
-
-The user must activate the factor to complete enrollment.
-
-<details>
-  <summary><b>Example Response</b></summary>
-
-  ```javascript
-  {
-    status: 'MFA_ENROLL_ACTIVATE',
-    expiresAt: '2014-11-02T23:39:03.319Z',
-    factorResult: 'WAITING', // or 'TIMEOUT',
-    user: {
-      id: '00ugti3kwafWJBRIY0g3',
-      profile: {
-        login: 'isaac@example.org',
-        firstName: 'Isaac',
-        lastName: 'Brock',
-        locale: 'en_US',
-        timeZone: 'America/Los_Angeles'
-      },
-    },
-    factor: {
-      id: 'opfh52xcuft3J4uZc0g3',
-      provider: 'OKTA',
-      factorType: 'push',
-      profile: {},
-      activation: {
-        expiresAt: '2015-04-01T15:57:32.000Z',
-        qrcode: {
-          href: 'https://acme.okta.com/api/v1/users/00ugti3kwafWJBRIY0g3/factors/opfh52xcuft3J4uZc0g3/qr/00fukNElRS_Tz6k-CFhg3pH4KO2dj2guhmaapXWbc4',
-          type: 'image/png'
-        }
-      }
-    },
-    resend: function() { /* returns another transaction */ },
-    activate: function(options) { /* returns another transaction */ },
-    poll: function() { /* returns another transaction */ },
-    prev: function() { /* returns another transaction */ },
-    cancel: function() { /* terminates the auth flow */ },
-    data: { /* the parsed json response */ }
-  }
-  ```
-
-</details>
-
-##### `resend()`
-
-Send another OTP if user doesn’t receive the original activation SMS OTP.
-
-```javascript
-transaction.resend();
-```
-
-##### `activate(options)`
-
-* `passCode` - OTP- sent to device for [activation](https://developer.okta.com/docs/api/resources/authn#activate-sms-factor)
-
-```javascript
-transaction.activate({
-  passCode: '615243'
-});
-```
-
-##### `poll()`
-
-[Poll](https://developer.okta.com/docs/api/resources/authn#activate-push-factor) until factorResult is not WAITING. Throws AuthPollStopError if prev, resend, or cancel is called.
-
-```javascript
-transaction.poll();
-```
-
-##### `prev()`
-
-End current factor enrollment and [return to](https://developer.okta.com/docs/api/resources/authn#previous-transaction-state) `MFA_ENROLL`.
-
-```javascript
-transaction.prev();
-```
-
-#### MFA_REQUIRED
-
-The user must provide additional verification with a previously enrolled factor.
-<details>
-  <summary> <b>Example Response</b> </summary>
+const authClient = new OktaAuth({
+  issuer: 'https://{yourOktaDomain}',
 
-  ```javascript
-  {
-    status: 'MFA_REQUIRED',
-    expiresAt: '2014-11-02T23:39:03.319Z',
-    user: {
-      id: '00ugti3kwafWJBRIY0g3',
-      profile: {
-        login: 'isaac@example.org',
-        firstName: 'Isaac',
-        lastName: 'Brock',
-        locale: 'en_US',
-        timeZone: 'America/Los_Angeles'
-      },
-    },
-    factors: [{
-      id: 'ufsigasO4dVUPM5O40g3',
-      provider: 'OKTA',
-      factorType: 'question',
-      profile: {
-        question: 'disliked_food',
-        questionText: 'What is the food you least liked as a child?'
-      },
-      verify: function(options) { /* returns another transaction */ }
-    }, {
-      id: 'opfhw7v2OnxKpftO40g3',
-      provider: 'OKTA',
-      factorType: 'push',
-      profile: {
-        credentialId: 'isaac@example.org',
-        deviceType: 'SmartPhone_IPhone',
-        keys: [
-          {
-            kty: 'PKIX',
-            use: 'sig',
-            kid: 'default',
-            x5c: [
-              'MIIBIjANBgkqhkiG9w0BAQEFBAOCAQ8AMIIBCgKCAQEAs4LfXaaQW6uIpkjoiKn2g9B6nNQDraLyC3XgHP5cvX/qaqry43SwyqjbQtwRkScosDHl59r0DX1V/3xBtBYwdo8rAdX3I5h6z8lW12xGjOkmb20TuAiy8wSmzchdm52kWodUb7OkMk6CgRJRSDVbC97eNcfKk0wmpxnCJWhC+AiSzRVmgkpgp8NanuMcpI/X+W5qeqWO0w3DGzv43FkrYtfSkvpDdO4EvDL8bWX1Ad7mBoNVLWErcNf/uI+r/jFpKHgjvx3iqs2Q7vcfY706Py1m91vT0vs4SWXwzVV6pAVjD/kumL+nXfzfzAHw+A2vb6J2w06Rj71bqUkC2b8TpQIDAQAB'
-            ]
-          }
-        ],
-        name: 'Isaac\'s iPhone',
-        platform: 'IOS',
-        version: '8.1.3'
-      },
-      verify: function() { /* returns another transaction */ }
-    }, {
-      id: 'smsigwDlH85L9FyQK0g3',
-      provider: 'OKTA',
-      factorType: 'sms',
-      profile: {
-        phoneNumber: '+1 XXX-XXX-3355'
-      },
-      verify: function() { /* returns another transaction */ }
-    }, {
-      id: 'ostigevBq2NObXmTh0g3',
-      provider: 'OKTA',
-      factorType: 'token:software:totp',
-      profile: {
-        credentialId: 'isaac@example.org'
-      },
-      verify: function() { /* returns another transaction */ }
-    }, {
-      id: 'uftigiEmYTPOmvqTS0g3',
-      provider: 'GOOGLE',
-      factorType: 'token:software:totp',
-      profile: {
-        credentialId: 'isaac@example.org'
-      },
-      verify: function() { /* returns another transaction */ }
-    }],
-    cancel: function() { /* terminates the auth flow */ },
-    data: { /* the parsed json response */ }
+  // headers can be set during construction
+  headers: {
+    foo: 'bar'
   }
-  ```
-
-  </details>
-
-##### [Verify Factor](https://developer.okta.com/docs/api/resources/authn#verify-factor)
-
-To verify a factor, select one from the factors array, then use the following methods.
-
-```javascript
-var factor = transaction.factors[/* index of the desired factor */];
-```
-
-###### [OKTA question](https://developer.okta.com/docs/api/resources/authn#verify-security-question-factor)
-
-```javascript
-var questionFactor = transaction.factors.find(function(factor) {
-  return factor.provider === 'OKTA' && factor.factorType === 'question';
 });
 
-questionFactor.verify({
-  answer: 'mayonnaise'
+// Headers can be set (or modified) after construction
+authClient.setHeaders({
+  foo: 'baz'
 });
-```
-
-###### [OKTA push](https://developer.okta.com/docs/api/resources/authn#verify-push-factor)
 
-* `autoPush` - Optional parameter to send a push notification immediately the next time `verify` is called on a push factor
-
-```javascript
-var pushFactor = transaction.factors.find(function(factor) {
-  return factor.provider === 'OKTA' && factor.factorType === 'push';
-});
-
-pushFactor.verify({
-  autoPush: true
-});
-```
-
-###### [All other factors](https://developer.okta.com/docs/api/resources/authn#verify-factor)
-
-```javascript
-var factor = transaction.factors.find(function(factor) {
-  return factor.provider === 'YOUR_PROVIDER' && factor.factorType === 'yourFactorType';
-});
-
-factor.verify();
-```
-
-#### MFA_CHALLENGE
-
-The user must verify the factor-specific challenge.
-<details>
-  <summary><b>Example Response</b></summary>
-
-  ```javascript
-  {
-    status: 'MFA_CHALLENGE',
-    expiresAt: '2014-11-02T23:39:03.319Z',
-    factorResult: 'WAITING', // or CANCELLED, TIMEOUT, or ERROR
-    user: {
-      id: '00ugti3kwafWJBRIY0g3',
-      profile: {
-        login: 'isaac@example.org',
-        firstName: 'Isaac',
-        lastName: 'Brock',
-        locale: 'en_US',
-        timeZone: 'America/Los_Angeles'
-      },
-    },
-    factor: {
-      id: 'smsigwDlH85L9FyQK0g3',
-      factorType: 'sms',
-      provider: 'OKTA',
-      profile: {
-        phoneNumber: '+1 XXX-XXX-6688'
-      }
-    },
-    verify: function(options) { /* returns another transaction */ },
-    poll: function() { /* returns another transaction */ },
-    prev: function() { /* returns another transaction */ },
-    cancel: function() { /* terminates the auth flow */ },
-    data: { /* the parsed json response */ }
-  }
-  ```
-
-</details>
-
-##### `verify(options)`
-
-* `passCode` - OTP sent to device
-* `autoPush` - Optional parameter to send a push notification immediately the next time [`verify`](https://developer.okta.com/docs/api/resources/authn#verify-factor) is called on a push factor
-
-```javascript
-transaction.verify({
-  passCode: '615243',
-  autoPush: true
-});
-```
-
-##### `poll(options)`
-
-* `autoPush` - Optional parameter to send a push notification immediately the next time `verify` is called on a push factor
-
-[Poll](https://developer.okta.com/docs/api/resources/authn#activate-push-factor) until factorResult is not WAITING. Throws AuthPollStopError if prev, resend, or cancel is called.
-
-```javascript
-transaction.poll({
-  autoPush: true
-});
+// Headers can be removed
+authClient.setHeaders({
+  foo: undefined
+})
 ```
 
-##### `prev()`
-
-End current factor verification and [return to](https://developer.okta.com/docs/api/resources/authn#previous-transaction-state) `MFA_REQUIRED`.
-
-```javascript
-transaction.prev();
-```
+### `tx.resume()`
 
-#### SUCCESS
+See [authn API](docs/authn.md#txresume).
 
-The end of the authentication flow! This transaction contains a sessionToken you can exchange for an Okta cookie, an `id_token`, or `access_token`.
+### `tx.exists()`
 
-<details>
-  <summary><b>Example Response</b></summary>
+See [authn API](docs/authn.md#txexists).
 
-  ```javascript
-  {
-    expiresAt: '2015-06-08T23:34:34.000Z',
-    status: 'SUCCESS',
-    sessionToken: '00p8RhRDCh_8NxIin-wtF5M6ofFtRhfKWGBAbd2WmE',
-    user: {
-      id: '00uhm5QzwyZZxjrfp0g3',
-      profile: {
-        login: 'exampleUser@example.com',
-        firstName: 'Test',
-        lastName: 'User',
-        locale: 'en_US',
-        timeZone: 'America/Los_Angeles'
-      }
-    }
-  }
-  ```
+### `transaction.status`
 
-</details>
+See [authn API](docs/authn.md#transactionstatus).
 
 ### `session`
 
 #### `session.setCookieAndRedirect(sessionToken, redirectUri)`
 
-> :link: web browser only <br>
-> :warning: method requires access to [third party cookies] <br>(#third-party-cookies)
-
-This allows you to create a session using a sessionToken.
-* `sessionToken` - Ephemeral one-time token used to bootstrap an Okta session.
-* `redirectUri` - After setting a cookie, Okta redirects to the specified URI. The default is the current URI.
-
-```javascript
-authClient.session.setCookieAndRedirect(transaction.sessionToken);
-```
+See [authn API](docs/authn.md#sessionsetcookieandredirectsessiontoken-redirecturi).
 
 #### `session.exists()`
 
@@ -2230,7 +1315,7 @@ authClient.token.getWithPopup(options)
 > :link: web browser only <br>
 > :hourglass: async
 
-Create token using a redirect. After a successful authentication, the browser will be redirected to the configured [redirectUri](#additional-options). The authorization code, access, or ID Tokens will be available as parameters appended to this URL. Values will be returned in either the search query or hash fragment portion of the URL depending on the [responseMode](#responsemode)
+Create token using a redirect. After a successful authentication, the browser will be redirected to the configured [redirectUri](#configuration-options). The authorization code, access, or ID Tokens will be available as parameters appended to this URL. Values will be returned in either the search query or hash fragment portion of the URL depending on the [responseMode](#responsemode)
 
 * `options` - See [Authorize options](#authorize-options)
 
@@ -2275,7 +1360,7 @@ authClient.token.parseFromUrl()
 });
 ```
 
-After reading values, this method will rewrite either the hash fragment or search query portion of the URL (depending on the [responseMode](#responsemode)) so that the code or tokens are no longer present or visible to the user. For this reason, it is recommended to use a dedicated route or path for the [redirectUri](#additional-options) so that this URL rewrite does not interfere with other URL parameters which may be used by your application. A complete login flow will usually save the current URL before calling `getWithRedirect` and restore the URL after saving tokens from `parseFromUrl`.
+After reading values, this method will rewrite either the hash fragment or search query portion of the URL (depending on the [responseMode](#responsemode)) so that the code or tokens are no longer present or visible to the user. For this reason, it is recommended to use a dedicated route or path for the [redirectUri](#configuration-options) so that this URL rewrite does not interfere with other URL parameters which may be used by your application. A complete login flow will usually save the current URL before calling `getWithRedirect` and restore the URL after saving tokens from `parseFromUrl`.
 
 ```javascript
 // On any page while unauthenticated. Begin login flow
@@ -2600,6 +1685,10 @@ authClient.authStateManager.subscribe((authState) => {
 
 Gets latest evaluated `authState` from the `authStateManager`. The `authState` (a unique new object) is re-evaluated when `authStateManager.updateAuthState()` is called. If `updateAuthState` has not been called, or it has not finished calculating an initial state, `getAuthState` will return `null`.
 
+#### `authStateManager.getPreviousAuthState()`
+
+Gets the previous evaluated `authState` from the `authStateManager`. This state can be used to tell when the new authState is evaluated. For example, the `authState` is evaluated duing app initialization if the `previousAuthState` is `null`, and the `authState` is evaluated during tokens auto renew process if the `previousAuthState` exists.
+
 #### `authStateManager.updateAuthState()`
 
 Produces a unique `authState` object and emits an `authStateChange` event. The [authState](#authstatemanager) object contains tokens from the `tokenManager` and a calculated `isAuthenticated` value. By default, `authState.isAuthenticated` will be true if both `idToken` and `accessToken` are present. This logic can be customized by defining a custom [transformAuthState](#transformauthstate) function.
@@ -2791,4 +1880,4 @@ const OktaAuth = require('@okta/okta-auth-js').OktaAuth;
 
 ## Contributing
 
-We're happy to accept contributions and PRs! Please see the [contribution guide](contributing.md) to understand how to structure a contribution.
+We're happy to accept contributions and PRs! Please see the [contribution guide](CONTRIBUTING.md) to understand how to structure a contribution.