README.md

@okta/okta-auth-js/myaccount / Exports

MyAccount API

Introduction

MyAccount APIs enables end user account management in SPA applications. The API requires an access token obtained via OAuth flows with additional scopes.

Scopes

The following scopes are required for permission to read/write the resources exposed by the MyAccount API:

profile:

okta.myAccount.profile.read
okta.myAccount.profile.manage

email:

okta.myAccount.email.read
okta.myAccount.email.manage

phone:

okta.myAccount.phone.read
okta.myAccount.phone.manage

password:

okta.myAccount.password.read
okta.myAccount.password.manage

Accessing API methods

Via NPM module

MyAccount API is published as a submodule under @okta/okta-auth-js package, you can access the myaccount module by following the snippets below:

ES module:

import { getEmails } from '@okta/okta-auth-js/myaccount';

CommonJS:

const { getEmails } = require('@okta/okta-auth-js/myaccount');

Via CDN

The built library bundle is also available on our global CDN. Include the following script in your HTML file to load before your application script:

⚠️ The version shown in this sample may be older than the current version. We recommend using the highest version available

<script src="https://global.oktacdn.com/okta-auth-js/6.7.0/okta-auth-js.min.js" type="text/javascript"></script>

Then you can create an instance of the OktaAuth object, available globally, then access MyAccount API methods under myaccount namespace.

const oktaAuth = new OktaAuth({
  // config
});
const emails = await oktaAuth.myaccount.getEmails();

Using types

Types are exposed from both module level and SDK entries, for environment with typescript version 4.7 or above, you can import types from both module and SDK entries. But if you are with lower typescript versions, please import types from the main SDK entry.

See typescript release notes for detailed information.

Import from module entry

import { getEmail } from '@okta/okta-auth-js/myaccount';

Import from SDK entry

import { getEmail } from '@okta/okta-auth-js';

Handling insufficient_authentication_context error

For additional security, the MyAccount API requires a higher assurance level to protect the end user's account from being manipulated by malicious actors. If the access token provided does not meet the required assurance level, an error will be thrown to prompt the user to re-authenticate. Applications consuming the MyAccount API will need to handle this error condition. When this occurs, myaccount methods will throw an AuthApiError with insufficient_authentication_context in errorSummary having max_age and acr_values in meta field, like so:

{
  name: 'AuthApiError',
  errorSummary: 'insufficient_authentication_context',
  errorCauses: [{
    errorSummary: 'The access token requires additional assurance to access the resource'
  }],
  meta: {
    max_age: 900,
    acr_values: 'phr'
  }
}

Re-authentication Approaches:

Re-Authenticate with Okta Hosted Login flow

Bootstrap re-authentication flow by calling getWithRedirect with maxAge and acrValues.

await getWithRedirect(
  oktaAuth,
  {
    prompt: 'login',
    maxAge,
    acrValues,
    scopes,
    extraParams: {
      id_token_hint: idToken
    }
  }
);

Re-Authenticate with Embedded SDK

Bootstrap re-authentication flow by calling oktaAuth.idx.authenticate with maxAge and acrValues.

const transaction = await oktaAuth.idx.authenticate({ maxAge, acrValues });
// then render form based on new transaction

Re-Authenticate with Embedded Widget

Bootstrap embedded widget by passing max_age and acr_values in authParams. Then start authentication flow from there.

const { issuer, clientId, redirectUri, scopes } = oidcConfig;
const widget = new OktaSignIn({
  baseUrl: issuer.split('/oauth2')[0],
  clientId,
  redirectUri,
  authParams: {
    scopes,
    ...(maxAge && { maxAge }),
    ...(acrValues && { acrValues }),
  },
  useInteractionCodeFlow: true,
});

API reference documentation

See MyAccount API reference documentation for detailed API definitions.