Authentication

Highlight features a robust authentication system designed to make onboarding new users seamless and secure along with making sign in for existing users a breeze. You can instantly generate access tokens from within the Highlight runtime but we also act as an OAuth 2.0 provider which allows your web apps to “Sign in with Highlight”.

​

Prerequisites

• A Highlight Developer account
• Basic understanding of OAuth 2.0
• Understanding of the Highlight Runtime API

​

Getting Started

Before you can use any of the Highlight auth functionality, you must create an application from the Developer Dashboard.

Take note of your client ID and save your client secret someplace secure. You will need this to refresh auth tokens later on. Add authorized redirect URIs if you want to use the “Sign in with Highlight” authorization grant flow. Any redirect_uri you wish to take the user to must be within this list.

​

Flows

​

Authenticating within Highlight

The easiest way to authenticate is if your web app is actively running within Highlight. You will get access to the Highlight.auth.signIn() method which automatically generates a fresh auth token and refresh token, skipping the normal OAuth flow. The refresh token can then be used to acquire a new access token when the original one expires. This must be done from a backend, never assume the client is secure.

Here’s an example of how you can authenticate using the Highlight runtime, this code is meant from within your client side app while your app is inside of Highlight:

​

Authenticating outside of Highlight

Highlight supports OAuth 2.0 authorization grant flow. To use this flow, you will need to redirect the user to the Highlight authorization page. This page will prompt the user to sign in and grant your application access to their account. You may only use redirect_uri’s that are listed in the Developer Dashboard.

1. Redirect the user to: https://auth.highlight.ing/authorize?client_id={client_id}&redirect_uri={redirect_uri}&response_type=code&state={state}
2. The user will be redirected back to your redirect_uri with a code parameter.
3. Send a POST request to the /token endpoint with the code parameter.

See “Exchanging a code for a token” below for more details.

​

OAuth Endpoints

​

Exchanging a code for a token

After the user is redirected back to your redirect_uri with a code parameter, you will need to send a POST request to the /token endpoint with the code parameter.

const formData = new FormData();
formData.append("grant_type", "authorization_code");
formData.append("code", "your_code");
formData.append("redirect_uri", "your_redirect_uri");
formData.append("client_id", "your_client_id");
formData.append("client_secret", "your_client_secret");

const response = await fetch(
  "https://backend.workers.highlight.ing/v1/auth/token",
  {
    method: "POST",
    body: formData,
  }
);

const tokensResponse = await response.json();

console.log("Access Token" + tokensResponse.access_token);
console.log("Refresh Token" + tokensResponse.refresh_token);

​

Refreshing a token

Regardless of how you authenticated (either through the Highlight app or the authorization grant flow), you will need to refresh your token. This can be done by sending a POST request to the /token endpoint.

const formData = new FormData();
formData.append("grant_type", "refresh_token");
formData.append("refresh_token", "your_refresh_token");
formData.append("client_id", "your_client_id");
formData.append("client_secret", "your_client_secret");

const response = await fetch(
  "https://backend.workers.highlight.ing/v1/auth/token",
  {
    method: "POST",
    body: formData,
  }
);

const tokensResponse = await response.json();

console.log("Access Token" + tokensResponse.access_token);
console.log("Refresh Token" + tokensResponse.refresh_token);

​

Fetching user information

To fetch user information, you can send a GET request to the /userinfo endpoint. This endpoint will return the user’s information.

const response = await fetch(
  "https://backend.workers.highlight.ing/v1/auth/userinfo",
  {
    method: "GET",
    headers: {
      "Authorization": "Bearer your_access_token"
    }
  }
);

const userInfoResponse = await response.json();