Fetch Token

Important

This feature is currently in Early Availability (EA) status. For more information, see our product lifecycle phases.

Overview

This guide describes how to get a JWT token from the API so you can authenticate requests to your external API.

Step-by-step instructions

The fetchExternalData function simplifies token use by automatically adding the token to the request header.

1. Begin by importing the serviceAuthToken object.

import serviceAuthToken from "../../functions/serviceAuthToken";

2. Call your external API using serviceAuthToken.fetchExternalData.

The function returns a promise that resolves to an object containing the data from the external API. It automatically includes the JWT in the request header as MP-Authorization.

# Example curl command to demonstrate JWT token inclusion
curl -X GET "http://example.com/api/auth/v1/sessions/userinfo" \
     -H "Accept: application/json" \
     -H "MP-Authorization: Bearer YOUR_JWT_TOKEN_HERE"

Example of the fetchExternalData usage:

const { errorMessage, status, response } = await serviceAuthToken.fetchExternalData(
    "http://example.com/api/auth/v1/sessions/userinfo", {
        method: "GET",
        credentials: "include",
        headers: {
            "Content-Type": "application/json",
        }},
    5000
);

Here, tokenInvalidTimer is set to 5000 ms (5 seconds).

caution

Calls to the external endpoint specified by url are not cached.

Parameters

1. url: The endpoint URL.
2. fetchOptions: An object in the same shape as the fetch API input, including all supported options.
3. tokenInvalidTimer: (Optional) How long to cache the JWT in memory.

note

tokenInvalidTimer can be set from 0 ms to 180000 ms (3 minutes). The default is 180000 ms.

Return value

1. errorMessage: Any error message returned.
2. status: The HTTP status (for example, 200, 500).
3. response: The response from the endpoint.

Manually fetching the JWT token

To retrieve the token yourself for use in custom hooks, use these serviceAuthToken functions:

1. getServiceAuthToken(tokenInvalidTimer)
2. reset()

1. getServiceAuthToken

This function returns a promise that resolves to an object containing the JWT token.

Example with tokenInvalidTimer set to 5000 milliseconds:

const { errorMessage, status, token } = await serviceAuthToken.getServiceAuthToken(5000);

Parameters

1. tokenInvalidTimer: (Optional) How long to cache the token in memory.

note

tokenInvalidTimer can be from 0 ms to 180000 ms (3 minutes). The default is 180000 ms.

Return value

1. errorMessage: Any error message returned.
2. status: The HTTP status (for example, 200, 500).
3. token: The JWT token.

2. reset

Clears the cached JWT token.

Complete Example

import React, { useState } from "react";
import serviceAuthToken from "../../functions/serviceAuthToken";

interface UserInfo {
  userName: string;
  email: string;
}

const App = (): JSX.Element => {
  const [userInfo, setUserInfo] = useState<UserInfo>();

  const callAPI = async (): Promise<void> => {
    const { errorMessage, status, response } =
      await serviceAuthToken.fetchExternalData(
        "http://example.com/api/auth/v1/sessions/userinfo",  // specify your endpoint URL
        {                                  // specify your fetchOptions
          method: "GET",
          credentials: "include",
          headers: {
            "Content-Type": "application/json",
          },
        },
        5000 // optional
      );

    const { userName, email } = response;
    setUserInfo({ userName, email });
  };

  return (
    <div data-e2e="microUIPage">
      <h2>Hello World!</h2>
      <div>Example API call to retrieve data:</div>
      <div>Username: {userInfo?.userName}</div>
      <div>Email: {userInfo?.email}</div>
      <button type="button" onClick={callAPI}>
        Call API
      </button>
    </div>
  );
};

export default App;