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), which can be helpful for organizations that make frequent permission changes or who want to manage workbook access and data warehouse access separately.

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. For example:

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 returns 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-tokens 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-tokens 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-tokens is set to true, Sigma rejects the “default” token (user A’s) and the exports fail to run.

Limitations