Use OAuth override tokens

The Sigma REST API supports the use of OAuth override tokens in API calls. OAuth override tokens allow users to temporarily use the OAuth permissions of another user when making API calls.

Using override tokens enables more fine-grained access to the data in your cloud data warehouse (CDW). This can be helpful for organizations with frequent CDW permissioning changes, or who want to keep their workbook access and data warehouse access separate.

An example use case is constraining access to the API while keeping permissions separated. You can set up API credentials for one user, and provide override tokens to that user to mimic the CDW permissions of other users. For example, these override tokens can be used when exporting data from a workbook with the Export data from a workbook endpoint. The API user can export workbooks that use data from connections they do not have access to by using the override tokens.

This document explains how to use override tokens in your API calls and how to enable or disable default override tokens. These tokens only affect permissions in your CDW, and do not override any Sigma permissions.

System and user requirements

You must use OAuth to manage permissioning between Sigma and your CDW.
Ensure you have the OAuth access tokens you want to use from your identity provider.

Using OAuth override tokens

To use OAuth override tokens in your API calls, use the x-sigma-oauth-overrides header.

curl --location 'https://api.sigmacomputing.com/v2/workbooks/{workbookId}/export' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'x-sigma-oauth-overrides: [{"conn_id":"connection-id-1", "token":"{"oauth_token}},{"conn_id":"connection-id-2", "token":"{oauth_token}]' \
--header 'x-sigma-oauth-reject-default-tokens: true' \

To obtain your connection IDs (conn_id), use the List connections endpoint. You can obtain the OAuth access tokens from your identity provider. If you are using the override tokens for workbooks that draw from multiple data sources, you will need a different OAuth token for each connection.

OAuth override tokens only change access to permissions in your CDW, and do not affect Sigma user permissions. If a user references a workbook they do not have access to in their API call, the call will return an error.

In Python, this might look like:

import requests
import json

url = "https://api.sigmacomputing.com/v2/workbooks/{workbookId}/export"

payload = json.dumps({
"format": {
"type": "pdf",
"layout": "portrait"
}
})
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'x-sigma-oauth-overrides': '[{"conn_id":"connection-id-1", "token”:”{oauthToken}”,{“conn_id":"connection-id-2", "token”:”{oauthToken}”]’,
'x-sigma-oauth-reject-default-tokens': 'true',
'Authorization': ‘redacted
}

response = requests.request("POST", url, headers=headers, data=payload)

In Javascript, this might look like:

const myHeaders = new Headers();
myHeaders.append("Content-Type", "application/json");
myHeaders.append("Accept", "application/json");
myHeaders.append("x-sigma-oauth-overrides", "[{\"conn_id\":\"connection-id-1\", \"token\":\"{oauthtoken}\"},{\"conn_id\":\"connection-id-2\", \"token\":\"{oauthToken}\"}]");
myHeaders.append("x-sigma-oauth-reject-default-tokens", "true");
myHeaders.append("Authorization", "Bearer [redacted]);

const raw = JSON.stringify({
  "format": {
    "type": "pdf",
    "layout": "portrait"
  }
});

const requestOptions = {
  method: "POST",
  headers: myHeaders,
  body: raw,
  redirect: "follow"
};

fetch("https://api.sigmacomputing.com/v2/workbooks/{workbookId}/export", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));

Enable or disable default OAuth override tokens

You can enable or disable the use of default OAuth override tokens using the x-sigma-oauth-reject-default-token header. This is an optional header.

This header controls fallback behavior when an override token isn’t provided for a connection. The “default” token is the OAuth token associated with the user making the API call.

For example, you might have a workbook that retrieves data from 2 connections. User A is making the API call, and has provided user B’s override token for one of the connections, but not the other. If x-sigma-oauth-reject-default-token is not set, or set to false, Sigma uses the “default” token (user A’s OAuth token) for the other connection.

However, if x-sigma-oauth-reject-default-token is set to true, Sigma rejects the “default” token (user A’s) and the exports fail to run.

Limitations

OAuth override tokens do not work for the following endpoints: List SQL queries in a workbook, Get the SQL query for a workbook element.
Not all of the public API endpoints utilize OAuth tokens. Endpoints related to metadata and Sigma app management, such as the List members, List grants, Get users for a user attribute and Get tags endpoints, do not communicate with CDWs. This means OAuth override tokens cannot be used for these endpoints.