How to use WAT as a bearer token [Linux]

Step-by-Step Guide: 

Why WAT is not a Bearer Token

Technically, the Web Access Token (WAT) is a token, but it is not a standard bearer token. This means it cannot be used directly in the Authorization header of an API request. WAT is designed primarily for embedding and Viewer access. To interact with APIs, it must first be exchanged for a session token. This exchange happens automatically when using Sisense.js or the Embed SDK.

Other Options

• When working inside a plugin or script, you don’t need to worry about authentication because you’re already authenticated.
• You can also use InternalHttp, a function on the Sisense Prism object, which mimics internal Sisense API requests. For more details, see Using InternalHttp.
  Note: Some requests that work outside of WAT may fail when called via InternalHttp while using WAT. This is a known limitation.
• For standard API access, it’s recommended to use bearer tokens. These are the officially documented methods for authenticating API endpoints and can access all endpoints, not just Viewer APIs. You can obtain them via user API tokens or the authentication endpoints.

Use WAT

Assuming you already have a valid WAT, the first step is to exchange it for a session token. This endpoint is undocumented and may change in future updates. It is the same internal route used by Sisense.js and the Embed SDK.

**Before proceeding, you can verify your token directly within Sisense.

async () => {
  const data = await fetch(`<YOUR_SISENSE_URL>/api/v1/wat/sessionToken`, {
    method: 'POST',
    headers: {
      'content-type': 'application/json',
    },
    body: JSON.stringify({ webAccessToken: wat }),
  }).then((res) => res.json());
  return data;
}

This route returns two key properties:

• initializer – Identifies the session token origin and helps Sisense track it.
• webSessionToken – The token used for authenticated API requests.

Include both in your request headers to make API calls:

const data = await fetch(
  `<YOUR_SISENSE_URL>/api/datasources/${encodeURI(datasource.title)}/jaql`,
  {
    method: 'POST',
    headers: {
      authorization: sessionData.webSessionToken,
      initialiser: sessionData.initialiser,
    },
    body: JSON.stringify(jaqlQuery),
  },
).then((res) => res.json());

This allows you to perform any API request while the session remains valid.

Limitations

• Since this route is undocumented, it may change in future Sisense releases. Always verify your implementation after upgrades.
• WAT is viewer-only, which applies to API endpoints as well. It can only be used for actions viewers are allowed to perform.
• WAT is not compatible with Sisense Multitenancy.
• Additional limitations can be found in Web Access Token documentation

For production environments, it’s recommended to use bearer tokens for full API access and long-term stability.

Conclusion

Web Access Tokens (WAT) are useful for embedding and Viewer access, but require an extra step to exchange for a session token to access APIs. This method is undocumented, mirrors internal Sisense processes, and is limited to viewer-level API access. For full API access and stability, use bearer tokens, the official and documented method.

References/Related Content 

• Using WAT with RESTful API
• Using Web Access Tokens
• Using the InternalHttp Function Within Scripts and Plugins
• Using WAT in iFrames
• Using WAT in Embed SDK
• Using WAT in SisenseJS
• Testing an Existing Web Access Token

Disclaimer: This post outlines a potential custom workaround for a specific use case or provides instructions regarding a specific task. The solution may not work in all scenarios or Sisense versions, so we strongly recommend testing it in your environment before deployment. If you need further assistance with this, please let us know.