Run a workbook with service account credentials

If you use OAuth to connect to your data platform, you might want some workbooks to run using service account credentials instead of as the individual users viewing the workbook. For example, if your workbook contains critical scheduled exports and materializations owned by a user that inconsistently accesses the workbook. If that user’s OAuth token expires, the exports and materializations fail to run.

Running a workbook with service account credentials can also improve performance for users on connections authenticated with OAuth using a result cache.

When queries run with individual OAuth credentials, Sigma does not reuse cached results from the query ID cache or the universal result cache. Running as a service account allows Sigma to reuse cached query results, which improves performance. Cached results from queries run as a service account can return results that don’t match the permissions of a users’ individual OAuth credentials. For more information, see Caching and data freshness.

You can set a workbook to run using service account credentials in one of two ways, depending on the configuration of the OAuth connection to your data platform used for the workbook data sources:

The connection uses the same OAuth configuration as the one used to log in to your Sigma organization (organization-level OAuth): A user assigned the Admin account type, or the workbook owner when their account type includes the Run workbooks as service account permission, can configure the workbook to run queries using the service account configured on the connection. See the requirements and setup instructions.
The connection uses an OAuth configuration specific to the connection (connection-level OAuth): A user with access to edit the workbook can swap the data source of the workbook to a different connection configured with service account credentials.

When you turn on Run as service account, Sigma runs queries on each OAuth connection in the workbook with the service account configured for that connection. If an OAuth connection has no service account configured, queries on that connection fail, and Sigma displays an error. For data from a non-OAuth connection, Sigma evaluates the workbook owner’s access to the source data.

If you choose to run a workbook using service account credentials, Sigma queries data and evaluates permissions for the workbook differently. Refer to the following table to compare the behavior across different settings:

Connection used as workbook data source	Is Run as service account configured?	How Sigma queries data and evaluates permissions
Workbook using a non-OAuth connection.	N/A	Sigma evaluates the workbook owner’s access to the source data and runs queries using the user account credentials set in the connection settings.
Workbook using an OAuth connection.	Yes	Sigma queries the published version of the workbook using the service account credentials configured for the connection whenever the workbook is viewed from within Sigma or run as part of a scheduled export. This ensures that any user with access to the workbook can view it, regardless of their data access in the data platform. If the connection has no service account configured, queries fail.
Workbook using an OAuth connection.	No	Sigma always runs queries with the user’s OAuth credentials, including when viewing workbooks owned by others.
Workbook using some data from an OAuth connection and other data from a non-OAuth connection.	Yes	For data from an OAuth connection, Sigma runs queries for the published version of the workbook using the service account credentials configured on the connection whenever the workbook is viewed within Sigma or run as part of a scheduled export. This ensures that any user with access to the workbook can view that data, regardless of their data access in the data platform. If the OAuth connection has no service account configured, queries on that connection fail. For data from the non-OAuth connection, Sigma evaluates the workbook owner’s permission to the source data and runs queries using the user account credentials set in the connection settings.
Workbook using some data from an OAuth connection and other data from a non-OAuth connection	No	For data from the OAuth connection, Sigma always runs queries with the user’s OAuth credentials using the permissions configured in the IdP, including when users are viewing workbooks owned by others. For the data from the non-OAuth connection, Sigma evaluates the workbook owner’s permission to the source data and runs queries using the user account credentials set in the connection settings.
Workbook using data from two different OAuth connections with different OAuth configurations.	Yes	Sigma runs queries for the published version of the workbook using the service account credentials configured on each OAuth connection whenever the workbook is viewed in Sigma or run as part of a scheduled export. This ensures that any user with access to the workbook can view that data, regardless of their data access in the data platform. If an OAuth connection has no service account configured, queries on that connection fail.
Workbook using data from two different OAuth connections with different OAuth configurations.	No	Sigma always runs queries with the user’s OAuth credentials configured for each connection, using the permissions configured in the IdP, including when users are viewing workbooks owned by others.

Requirements

To configure this setting, you must have the Admin account type or own the workbook and have an account type with the Run workbooks as service account permission. See Account type and license overview.
The Run as service account option is available for any workbook when your organization has an active OAuth connection configured. If you turn it on for an OAuth connection with no service account configured, queries on that connection fail. For information on how to configure a service account for a connection, see:

Run an individual workbook as a service account

Open the workbook.
Click the down arrow () to open the workbook menu.
Select Share….
Turn on the Run as service account toggle.