Fetch Token

Important

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

Overview

This guide details the process of acquiring a JWT token from our API, which is essential for authenticating requests to your API.

Step-by-Step Instructions

To simplify the use of our JWT token, you can utilize the fetchExternalData function, which automatically appends 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.

This function issues a promise that resolves to an object containing the data from the external API. It automatically includes our JWT token in the header under 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
);

In this instance, tokenInvalidTimer is set to 5000ms, or 5 seconds.

caution

The external endpoint call defined by url is NOT cached.

Parameters:

1. url: URL of the desired endpoint.
2. fetchOptions: an object structurally similar to the fetch API's input, including all its attributes.
3. tokenInvalidTimer: an optional parameter that sets the duration for JWT token caching in memory.

note

The tokenInvalidTimer can be set from 0ms to 180000ms (3 minutes), with a default of 180000ms.

Returned Object:

1. errorMessage: any error message received.
2. status: the network error status (e.g., 200, 500).
3. response: the response from the url endpoint.

Manually Fetching the JWT Token

If you prefer to manually retrieve the token for use with your custom hooks, you can use the following serviceAuthToken functions:

1. getServiceAuthToken(tokenInvalidTimer)
2. reset()

1. getServiceAuthToken

Calling this function returns a promise resolving to an object with the JWT token.

Example with tokenInvalidTimer set to 5000 milliseconds:

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

Parameters:

1. tokenInvalidTimer: an optional parameter for setting the token cache duration in memory.

note

The tokenInvalidTimer can be a value from 0ms to 180000ms (3 minutes), defaulting to 180000ms.

Returned Object:

1. errorMessage: any error message received.
2. status: the network error status (e.g., 200, 500).
3. token: the JWT token.

2. reset

This function 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;