Refreshing the Access Token

Ejento AI access tokens are short-lived for security. This guide explains how to obtain tokens through login, how to refresh them, and the flow around it — so you can keep a session authenticated from any client, whether you are building a frontend or a backend integration. The API interaction is identical in both cases; only where you store the tokens differs.

For a complete overview of every authentication option, see the Getting Started with Authentication guide.

The Tokens

When a user authenticates, you receive two tokens:

access_token — authorizes the authentication service, including the refresh endpoint itself.

ejento_access_token — authorizes your calls to the Ejento AI API (chat, agents, corpora, and so on).

Both tokens are time-limited and will eventually expire. The refresh endpoint lets you exchange your current access_token for a fresh pair of tokens before that happens — without asking the user to log in again.

Prerequisites

Your Ejento API key.

The Base URL for your Ejento environment.

Before you can refresh, you need an initial token pair. Ejento AI supports several login methods — see the Getting Started with Authentication guide for the full list. This guide uses Microsoft Azure AD (SSO) login as the example; whichever method you choose, the result is the same: an access_token and an ejento_access_token.

In short: You only call the Azure AD login endpoint once, during initial setup. Store the returned access_token and ejento_access_token — from here on, use the ejento_access_token to call the Ejento API and the access_token to refresh. You do not log in again: instead, call the refresh endpoint at least once every 6 days to obtain a fresh pair before the current tokens expire, and replace your stored tokens with the new ones. This keeps your session alive indefinitely without repeating the login step.

Step 1 — Get the Azure AD token (MSAL) (skip if you already obtain the token your own way)

The azure_ad_token used below comes from Microsoft's Authentication Library (MSAL). In short: configure MSAL with your Azure AD application, sign the user in, and acquire a token for your scope.

Note: The snippet below is only an example. If you already obtain Azure AD tokens some other way, keep using your existing approach — all Ejento needs is a valid azure_ad_token.

On a backend, use @azure/msal-node instead. See Microsoft's MSAL documentation for full setup.

Step 2 — Exchange it for Ejento tokens

Exchange the Azure AD token for Ejento tokens in a single request.

Endpoint:

Request headers:

Request body (JSON):

{
  "email": "[email protected]",
  "azure_ad_token": "<azure-ad-token>",
  "full_name": "Jane Doe", // optional
  "auto_create": true, // optional
  "organization_id": "<organization-id>" // optional
}

Field	Required	Description
`email`	Yes	The user's email address.
`azure_ad_token`	Yes	The token issued by Microsoft Azure AD.
`full_name`	No	Used when creating a new user.
`auto_create`	No	Create the user automatically if they do not exist.
`organization_id`	No	The organization to associate the user with.

Response — 200 OK

{
  "access_token": "<access token>",
  "ejento_access_token": "<ejento access token>",
  "token_type": "bearer"
}

Store the returned access_token and ejento_access_token. As described above, this login step happens only once — from here on you keep your session alive with the refresh endpoint.

The Refresh Endpoint

Exchange your current tokens for a new pair.

Headers

Header	Value	Description
`Authorization`	`Bearer {access_token}`	Your current `access_token`. This is what the endpoint authenticates.
`Ocp-Apim-Subscription-Key`	`{API_KEY}`	Your API key.

Request body

None. The refresh is driven entirely by the access_token in the Authorization header.

Successful response — 200 OK

{
  "success": true,
  "message": "Token refreshed",
  "data": {
    "access_token": "<new access token>",
    "ejento_access_token": "<new ejento access token>",
    "token_type": "bearer"
  }
}

Replace both of your stored tokens with the new values from data. The old tokens should no longer be used.

Error responses

Status	Meaning	What to do
`401 Unauthorized`	The `access_token` is invalid or has fully expired.	The session cannot be renewed. Send the user back through the login flow.
`422 Unprocessable Entity`	The request was malformed.	Check the `Authorization` header format and the API key.

When to Refresh

Refresh on a schedule. Because you log in with Azure AD only once, you keep the session alive by calling the refresh endpoint at least once every 6 days — before the current tokens expire — and storing the new pair each time.

The Flow, Step by Step

Store the token pair. After the one-time login, keep the access_token and ejento_access_token in secure storage (for example, Azure Key Vault).

Call the API. Send requests with Authorization: Bearer {ejento_access_token} and the Ocp-Apim-Subscription-Key header.

Refresh every 6 days. On a schedule, before the 7-day expiry, call POST /auth-service/api/v2/users/refresh-access-token with Authorization: Bearer {access_token} and the API key.

Store the new tokens. On 200, replace both stored tokens with the new access_token and ejento_access_token from data.

Keep calling the API with the refreshed ejento_access_token. Because you refresh ahead of expiry, requests never fail due to an expired token.

To prevent an endless loop, retry the original request only once after a refresh.

Summary

Obtain the initial access_token and ejento_access_token through a login endpoint (this guide uses Microsoft Azure AD SSO; see the Getting Started with Authentication guide for other methods).

You log in only once during setup; after that, refresh the tokens at least every 6 days to get a new pair without logging in again.

Authenticate the refresh call with your current access_token; you receive a new access_token and ejento_access_token.

Run only one refresh at a time and let concurrent requests share its result.

Authentication and Token Refresh Guide

Refreshing the Access Token#

The Tokens#

Prerequisites#

Obtaining the Tokens (Login)#

Step 1 — Get the Azure AD token (MSAL) (skip if you already obtain the token your own way)#

Step 2 — Exchange it for Ejento tokens#

The Refresh Endpoint#

When to Refresh#

The Flow, Step by Step#

Summary#