Revoke one or more login sessions for a user principal in an organization.

Note that a login session is what a user gets after logging into Fusion, InField, or another Cognite application. It is distinct from the concept of the "sessions" that can be used for background work like Transformations or Functions; however, each such background session is backed by a login session.

Upon successful completion of a login flow, the user receives an access token and a refresh token, which are both associated with the newly established login session. (Note that the user may have multiple concurrent login sessions.) The user may use the access token to send requests to the Cognite API, and the refresh token to obtain a new access token before the current one expires. Refreshing will also produce a new refresh token and invalidate the previous one. Every access token and refresh token in this "chain" is associated with the same login session.

Revoking a login session will set its status to REVOKED (which will be reflected in /api/v1/orgs/{org}/principals/{principal}/sessions), which within a short amount of time will prevent the user from accessing the Cognite systems via that login session. Specifically:

• Requests to the Cognite API that use any access token that is associated with this session will be rejected.
• Requests to refresh the login session will be rejected.
• Background jobs that were started from this login session will stop working. Note that this might take up to one hour to take effect.

Note that the user may still have other active login sessions, which will remain active. If you want to completely prevent a user from accessing Cognite systems, you should remove them from your organization's external identity provider (e.g. your Entra ID tenant), which will prevent them from logging in again, and then call /api/v1/orgs/{org}/principals/{principal}/sessions to list all their current login sessions and then pass all their ids to this endpoint (in batches, if there are more than 10) to revoke them.

Also note that because the REVOKED status is "stronger" than the LOGGED_OUT status (background sessions remain active in the latter status but not in the former), it is possible to revoke a login session that is LOGGED_OUT (which will stop any associated background sessions). Currently, REVOKED has the same consequences as EXPIRED, but revocation might be expanded in the future to become even stronger, so it is also possible to revoke a login session that is EXPIRED. Revoking a login session that is already REVOKED will succeed but will have no effect (in particular, the deactivatedTime of the login session will not change).

This endpoint is atomic: if revocation of any of the given login sessions fails, none of the login sessions will be revoked. In other words, any other status code than 204 means that no login sessions were revoked.

This endpoint does not work for service account principals, which do not have login sessions.

Access control

Requires the caller to be an admin of the target organization (it is not sufficient to be an admin of an ancestor organization).