API Bearer token lifecycle in Sisense [Linux]

Background

Personal API Bearer tokens allow you to authorize your requests to the Sisense API endpoints. See Using REST API for more details.

Creation

Each API Bearer Token is bound to a user who creates it and inherits permissions and access level. One user may create multiple tokens using one of the three APIs:

1. POST /api/v1/authentication/login - generates a Bearer token based on the provided username/password. Only available to users who have Sisense credentials.
2. GET /api/v1/authentication/tokens/api - generates a Bearer token of the currently logged-in user. Can be used by users who do not have Sisense native credentials, such as the SSO-integrated users.
3. POST /api/v1/authentication/tokens/api/renew - invalidates all previously issued Bearer tokens of the user and creates a new one.

Revocation

The user's API Bearer token can be invalidated due to certain user-level or system-level events. It is important to note that there is no way to invalidate a particular token of a user while keeping their other tokens valid, except by waiting for the token to expire.

All events mentioned below invalidate all tokens for a particular user (user-level events) or all users in the system (system-level events).

User events:

1. Sending a POST /api/v1/authentication/tokens/api/renew request.
2. Sending a DELETE /api/v1/authentication/admin/tokens/{tokenType} request (tokenType = api, users = userId).
3. For SSO JWT users:
1. If the [User Profile] > [API Token] feature is turned off:
• When a user logs out of Sisense, by either clicking the Logout button or calling a logout endpoint, such as /api/auth/logout.
• The Bearer token may be invalidated during a build of the Elasticube that is owned by an SSO JWT user and has Custom Code tables.

System events:

1. Changing the [Support Cross-Site Cookies for Embedding] mode in the [Security Settings] (e.g., from Default to None).
2. Switching the [Session Management] mode from [Cookie] to [Session Inactivity] and vice versa.
3. Sending the POST /api/v1​/authentication​/admin​/logout_all_users request.
4. Changing the secret in the extended [Security Settings].

Expiration

The expiration of Bearer tokens is a system-wide setting introduced in the L2024.1 version. 

The state of this feature can be viewed by running the GET /api/v1/settings​/system request. The corresponding parameter is called [apiTokenExpiration] under the [authentication] section. When [apiTokenExpiration] is enabled, the token expiration is defined based on the Session Management duration in the Security Settings (either Cookie or Session Inactivity, depending on the selected mode).

You can view the expiration time of a particular API Bearer token by JWT-decoding it and checking the ‘exp’ field.

More details: https://docs.sisense.com/main/SisenseLinux/sisense-bearer-tokens.htm.

Renew

The API bearer tokens include the expiration date in their structure. As such, it is not possible to renew a particular API Bearer Token. Instead, you can either generate a new token, or use a renew endpoint to invalidate all previously generated tokens for this user and create a new token.

 

What [User profile > API Token] controls

The [User Profile] > [API Token] system-wide parameter controls a few aspects of the Bearer tokens. When you enable the token, the following changes are applied in the system:

1. All users will see an API Token in their User Profile. Users can view and renew (rotate and create a new one) their API Bearer tokens.
2. Logout no longer invalidates all API Tokens for the SSO JWT users.
3. Execution of the Custom Code table no longer invalidates all API Tokens of the SSO JWT users.
4. POST /api/v1/authentication/tokens/api/renew endpoint becomes available in the system.

Best practices

• If you build an API integration, you may want to consider creating a dedicated Sisense user to execute API requests.
• Finish configuring the authentication and cookie settings in your environment before proceeding to develop API integration to avoid unexpected system-wide API Token revocations.
• If you plan to enable token expiration, carefully consider the session duration, as it will also affect the API Bearer Tokens.
• If you plan to use the API Bearer tokens as JWT SSO users, consider enabling [User Profile] > [API Token] setting to avoid token invalidations after some user actions.
• In case of the token expiration, implement logic that would regularly renew the token in your external integration.

Conclusion

• API Bearer tokens in Sisense are user-specific, inherit user permissions, and can be created via three different API endpoints, including SSO users.
• All tokens of a user can be invalidated due to specific user/system events; individual token revocation is not supported except via expiration.
• Expiration is controlled by a system-wide setting (“apiTokenExpiration”) and is linked to session management configurations.
• The [User Profile] > [API Token] setting modifies how tokens work for SSO JWT users, improving persistence after logout or custom code execution.

References/Related Content

• https://sisense.dev/guides/restApi/using-rest-api.html
• https://docs.sisense.com/main/SisenseLinux/sisense-bearer-tokens.htm
• https://community.sisense.com/kb/apis/beginner-sisense-rest-api-tips/9043
• https://community.sisense.com/kb/apis/curl-api-usage/9049
• https://community.sisense.com/kb/apis/access-sisense-api-from-postman/9048

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.