Configure API credentials and connectors in Sigma

You can configure API connectors and credentials for use in Sigma workbooks.

Connectors are used when configuring a Call API action. Along with an associated credential, connectors define an API request, governing which APIs and endpoints users can access when configuring an action in Sigma. For more on using connectors in a workbook, see Create actions that call API endpoints.

This document describes how to configure API connectors and credentials.

Understanding API connectors

Application programming interfaces (APIs) are protocols for how two pieces of software interact with one another and exchange information. In the case of a public API, an application’s developers configure the API so that external developers can retrieve or manipulate data in their application programmatically, without a user interface.

API connectors in Sigma allow you to pre-configure the details required to make a request in a Call API action, including the endpoint, HTTP method, authentication credentials, query parameters, request body, and more. Without a connector, you cannot configure a Call API action in a workbook.

API connectors can be associated with a credential. The credential contains the authentication information required to access the API, and you can use it when configuring an API connector. Not all API connectors require a credential. For example, a connector for a public API that does not require authentication does not need a credential.

The API you create a connector for might be your own, a Sigma API, or a third-party API. This document sometimes refers to the API you configure a connection for as a third-party API, indicating that the API is not managed by Sigma or by the user.

User requirements

• To create and manage API connectors and credentials, you must be assigned an account type with the Manage API connectors permission enabled.
• You must be able to provide the required authentication credentials for the API endpoint.

Add a new API credential to Sigma

Add a new API credential to Sigma before creating an API connector. For APIs that require authentication, you must create a credential to store the authentication information and use it in your connector. APIs that do not require authentication do not need a credential.

Before creating a credential, retrieve the required credentials for making requests to the API. Sigma supports the following authentication methods for API credentials:

• Bearer token
• Basic auth
• API key
• OAuth (client credentials)
• OAuth (authorization code)
• OAuth (password credentials)
• AWS Signature V4

Using the credentials you retrieved for the desired API, create a credential in Sigma:

1. Go to Administration > API connectors.

   1. From the Sigma header, click your user avatar to open the user menu.
   2. Select Administration to open the Administration portal.
   3. From the side panel, select API connectors.

2. Select the Credentials tab.

3. Click Create credential.

4. On the New credential screen, configure the following fields in the Credential details section to define the name, description, and authorized domains:

   Field	Description
   Name	The name of the credential as it appears in a connector.
   Description	(Optional) A description that helps users identify the credential.
   Authorized domains	A set of authorized domains used to restrict access to the credential. The credential can only be used for endpoints that match the authorized domains. Use * for a wildcard.

5. Select an Authentication method that you have the required credentials for and configure the fields in the Authentication details section:

6. Click Save.

The credential is created and appears in the Credentials tab.

For more information on how Sigma constructs the API request header based on the authentication method you select, see How Sigma handles authentication types in the request header.

How Sigma handles authentication types in the request header

Based on the authentication method you select when creating an API credential, Sigma constructs a header or query parameter with the credentials you provide. Review the following examples for how selected authentication methods are formatted in the request header:

• Bearer token
• Basic auth
• API key
• OAuth (client credentials)

Bearer token

For Bearer token, Sigma formats the header like the following:

Authorization: Bearer <token>

Here, <token> indicates the token you provide when creating the credential. The token is encrypted and never returned to the user.

Basic auth

For Basic auth, Sigma formats the header like the following:

Authorization: Basic <encoding>

Here, <encoding> is a Base64 encoding of the string username:password as you provide them when creating the credential. The password is encrypted and never returned to the user.

API key

For API key, Sigma formats the header like the following when the Pass in as option is set to Header:

key: value

For API key, Sigma formats the header like the following when the Pass in as option is set to Query parameter:

https://api.example.com/endpoint/?key=value

Here, key and value are the values you provided when creating the credential. The value is encrypted and never returned to the user.

OAuth (client credentials)

For OAuth (client credentials), Sigma makes a POST request at the Access token URL specified in the credential, and then uses the token in the header like a Bearer token:

Authorization: Bearer <token>

For OAuth (client credentials), if the Send client credentials as option is set to Basic auth header, Sigma formats the header like the following:

Authorization: Basic <encoding>

For OAuth (client credentials), if the Send client credentials as option is set to Body, Sigma formats the body like the following:

client_id=client_id_value&client_secret=client_secret_value

Create a new API connector in Sigma

You can create an API connector in Sigma to use in a Call API action.

Any user with access to this connector and an account type with the Create API actions permission can use the connector when configuring a Call API action.

To create a new API connector in Sigma:

1. Go to Administration > API connectors.

   1. From the Sigma header, click your user avatar to open the user menu.
   2. Select Administration to open the Administration portal.
   3. From the side panel, select API connectors.

2. Click Create connector.

3. On the New API connector screen, configure the following fields to define the connector:

   Field	Description
   Name	The name of the connector as it appears to users in a workbook.
   Description	(Optional) A description that helps users identify the connector and verify its contents.
   Credentials	(Optional) A credential from your configured API credentials in Sigma. See Add a new API credential to Sigma.
   Certificate	(Optional) A certificate from your configured certificates in Sigma. See Configure mutual transport layer security (mTLS) for API connectors in Sigma.
   Connector type	The type of connector. You can select Custom connector or via OpenAPI. If you select via OpenAPI, select a specification, base URL, and endpoint from that specification. For more information, see Import an OpenAPI specification.
   Base URL	An HTTP method and the URL for the request.
   Request headers	(Optional) A header for the request.
   Query parameters	(Optional) Query parameters for the request. For more information see Configure query parameters for an API connector.
   Path parameters	(Optional) Dynamic path parameters. To set path parameters, you must include /:<path_param> in the Base URL for each path parameter you want to configure. You can then configure the path parameter with a Static value or Dynamic values supplied by the workbook user when configuring a Call API action for the connector.
   Request body	(Optional) A request body, including form-data, or raw JSON, Text, and XML. For more information, see Configure a request body for an API connector.
   Response output	(Optional) A custom output, parsed from the response. To make use of the response data in a workbook, such as in controls or input tables, see Create custom action variables for an API connector.
   Advanced configuration	(Optional) Additional settings for governance and security, including retries, timeouts, and rate limiting. For more information, see Configure governance settings for an API connector.

4. Review the endpoint preview for accuracy.

5. (Optional) Select Test connector to test the connector.

6. Click Save.

To use your API connector in a workbook, see Create actions that call API endpoints.

Import an OpenAPI specification

When creating an API connector in Sigma, you can import an OpenAPI specification to create a connector:

1. Go to Administration > API connectors.

2. Click Create connector.

3. On the New API connector screen, open the Connector type dropdown and select via OpenAPI.

4. Under Select OpenAPI specification, select Manage OpenAPI.

5. In the OpenAPI modal, select Create new OpenAPI.

6. In the Create OpenAPI modal, configure the following fields:

   Field	Description
   Name	The name of the OpenAPI specification.
   Specification URL	The URL of the OpenAPI specification.

   For a step-by-step example of using an OpenAPI specification to create an API connector, follow the instructions in Tutorial: Configure API credentials, connectors, and actions for the Sigma REST API.

7. Click Create.

The OpenAPI specification is imported and appears in the Select OpenAPI specification dropdown in the New API connector screen. You can update or delete the OpenAPI specification in the OpenAPI modal.

Create an API connector based on a cURL request

If you have an existing client URL (cURL) request that you want to migrate to Sigma, you can create a new API connector by importing the cURL request:

1. Go to Administration > API connectors.

2. Click Create connector.

3. On the New API connector screen, select Import from cURL in the header.

4. In the Import from cURL modal, enter a valid cURL request.

   For example, to create a connector that calls the List data models endpoint, enter a request in the following format:

   Example cURL import format

   $
   curl --request GET \
   >
     --url <base_url>/v2/dataModels \
   >
     --header 'accept: application/json' 
   To test the request above, follow the instructions to Generate Sigma API credentials, store the token as an API credential used in the new connector, and enter the API request URL for your Sigma organization in place of the <base_url> placeholder.

5. Select Import.

   Sigma parses the cURL request for a URL, HTTP verb, headers, and request body and populates their details as fields in the New API connector screen.

6. After configuring the remaining fields in the New API connector screen, click Save.

Configure query parameters for an API connector

When creating an API connector in Sigma, you can optionally set query parameters in the Request details section of the New API connector screen:

1. Under Query parameters, click Add parameter.

2. For the query parameter, configure the following fields:

   Field	Description
   Key	The key for the query parameter.
   Mode	Select Static to set a static value, or Dynamic to set the value based on a selection in the workbook when configuring a Call API action.
   Value	The value for that query parameter. If Mode is set to Static, enter the value.

   To identify valid arguments you can use as query parameters, review the documentation for the API as you configure the connector.

3. After configuring the remaining fields in the New API connector screen, click Save.

For Static parameter values, you can set a key and value for the query parameter, which appear in the endpoint in the following way:

https://api.example.com/endpoint/?key=value

For example, if you configure a Static query parameter with the key limit and the value 100, the endpoint is constructed in the following way:

https://api.example.com/endpoint/?limit=100

For Dynamic parameter values, you can set a key for the query parameter, which appears in the endpoint preview like the following:

https://api.example.com/endpoint/?key={{key}}

The dynamic value {{key}} is populated by the user that creates a Call API action with this connector. Any user with access to this connector, as well as an account type with the Create API actions permission enabled, can use it in a workbook with any valid value for the query parameter.

Configure a request body for an API connector

When creating an API connector in Sigma, you can optionally configure a request body in the Request details section of the New API connector screen.

See the following sections for guidance on formatting a request body:

• Configure a request body as a set of key-value pairs
• Configure a request body as raw JSON, Text, or XML
• Configure a request body for a GraphQL endpoint
• Configure dynamic values and types in a request body

Configure a request body as a set of key-value pairs

To configure the request body as a series of key-value pairs:

1. Under Request body, select form-data.

2. For form-data, configure the following fields:

   Field	Description
   Key	The key for this object in the request body.
   Mode	Select Static to set a static value, or Dynamic to configure a dynamic value when using the connector in a Call API action in a workbook.
   Value	The value for that key in the request body. If Mode is set to Static, enter the value.

3. (Optional) To configure additional keys for the request body, click Add key and configure the fields as described in step 2.

4. After configuring the remaining fields in the New API connector screen, click Save.

Configure a request body as raw JSON, Text, or XML

To configure the request body as JSON, Text, or XML:

1. Under Request body, select raw.

2. In the dropdown, select JSON, Text, or XML.

3. In the text area, configure the request body for the connector.

   • If you configured any dynamic values in the request body, configure their types. For more information, see Configure dynamic values and types in a request body.
   When configuring a request body as JSON, you can select Beautify to automatically format the JSON in the text area, making it easier to read, edit, and organize nested objects.

4. After configuring the remaining fields in the New API connector screen, click Save.

Configure a request body for a GraphQL endpoint

Sigma supports queries and mutations to GraphQL endpoints in addition to traditional REST API endpoints.

To configure an API connector that targets a GraphQL endpoint:

1. Under Request body, select GraphQL.

   After selecting GraphQL, the HTTP method is set to POST, and the options to add Query parameters and Path parameters are removed.

2. Configure the following fields to define the request headers:

   Field	Description
   Key	The key for this object in the request header.
   Mode	Select Static to set a static value, or Dynamic to configure a dynamic value when using the connector in a Call API action in a workbook.
   Value	The value for that key in the request body. If Mode is set to Static, enter the value.

3. In the Request body field, define the query or mutation. If you configured any dynamic values in the request body, configure their types. For more information, see Configure dynamic values and types in a request body.

   For example, to configure a query against an endpoint that returns details on countries, and declare a dynamic $code input for the country, you can write a request body like the following:

   GraphQL query request body example

   query GetCountry($code: ID!) {
     country(code: $code) {
       name
       capital
       currency
       languages { name }
     }
   }

   Or, to configure a mutation that creates a new post in a social media feed, and declare a dynamic $input for the post’s contents, you can write a request body like the following:

   GraphQL mutation request body example

   mutation CreatePost($input: CreatePostInput!) {
     createPost(input: $input) {
       id
       title
       body
     }
   }

4. After configuring the remaining fields in the New API connector screen, click Save.

Configure dynamic values and types in a request body

When configuring a raw request body, you can add a dynamic value using the following syntax:

{{dynamic-value}}

When configuring a GraphQL request body, you can add a dynamic value using the following syntax:

$dynamic-value

When using a connector with a dynamic value in a Call API action in a workbook, users can populate the dynamic values with a Static value, Control value, or Formula.

You can also apply types to dynamic values in the request body to enforce the data type of that value when users create a Call API action in a workbook. After entering a dynamic value in the request body, open the Type dropdown and select one of the following types:

• Text
• Number
• Logical
• Variant
• Array

When users create a Call API action and populate a dynamic value with Static values, Sigma automatically applies the selected type. For example, if you configure a dynamic value with the type Text, Sigma automatically converts Static values to text when entered. If a user enters a number (e.g. 123), it is converted to a string (e.g. "123").

When users create a Call API action and populate a dynamic value with a Control value or Formula, Sigma performs validation for the selected type. For example, if you configure a dynamic value with the type Text, Sigma validates inputs from a Formula to ensure they are text data. If a user enters a number (e.g. 123) in the formula bar, Sigma shows an Invalid type error.

Controls are only shown in the Call API action if the type of the control matches the type of the dynamic value. For example, if you configure a dynamic value with the type Text, only controls with a Text type are shown.

Create custom action variables for an API connector

When creating an API connector in Sigma, you can parse the response to create custom variables for use in other workbook actions. For example, you can parse a response body, and then use that parsed response value in a Set control value action after calling the API to set the control based on the response from the API.

To add custom action variables while editing or creating an API connector:

1. Under Response output, click + Add.

2. For the new action variable, configure the following fields:

   Field	Description
   Variable name	The name of the action variable that appears in action sequences.
   Accessor	A formula used to parse the response from the API connector. For example, [response][0].key returns the value of the key property from the first object in an array of objects.
   Shape	The data type or shape of the action variable. You can either select a top-level type for a single value, such as Text, Number, Logical, or Variant, or select Array to parse the response into an array of values.

   Consider the data type of the response and the desired shape of the response variable when configuring the Shape and Accessor. For example, if you receive an array from the API connector, and want to return the first value of a field in the array to a Text control, select Text as the Shape, and use an accessor like [response][0].key.

3. Click Save.

The custom action variable is available to use in workbook action sequences that use the API connector in a Call API action. For more information on using the action variable in an action sequence, see Use variables in actions.

Parse an API response body into multiple rows in an input table (Beta)

You can parse an array from an API response body into multiple rows and columns in an input table using a custom action variable and the Insert row(s) action.

While creating a new API connector that returns an array in the response body, configure a custom action variable:

1. Under Response output, click + Add to add a new action variable.

2. For the new action variable, configure the following fields:

   Field	Setting
   Variable name	Enter a name for the action variable containing the array of values.
   Accessor	Enter a formula that returns an array. For example, if the response body returns only an array, enter [response]. Or, if the response body returns an object with an array as one of its properties, enter [response].<key>, replacing <key> with the identifier of the property.
   Shape	Select Array. Then, select an output type for the items within the array. For example, if the response array contains a series of product names, select Text to be able to insert them into a Text column in an input table.

3. (Optional) If you selected Object as the type for array items, select + Add key to parse one or more properties from the object and set their types in the output object. For example, if the API response body contains an array of objects with a numeric Id value, add a property labeled Id with a type of Number to add it to the action variable.

4. Click Save.

Then, in a workbook with an input table, add a Call API action that uses the API connector and writes to the input table:

1. In an action sequence, add a Call API action that uses the connector you defined an action variable for in the previous steps.

2. In the same action sequence, after the Call API action, add an Insert row(s) action, and configure it with the following settings:

   Field	Setting
   Action	Select Insert row(s).
   Insert type	Select Source data.
   Into	Select the input table to insert data from the API response into.
   From	Select Action variable and then select the action variable you defined previously.
   Set column values	For each column in the input table, select properties from the action variable to insert.

When the action sequence triggers, new rows are added based on each object in the response body.

For an end-to-end example that includes defining an API connector and action variable, as well as parsing the contents of that action variable into a table, see Tutorial: Configure API credentials, connectors, and actions for the NYC Open Data API.

Configure governance settings for an API connector

When creating an API connector in Sigma, you can configure advanced settings to control timeouts, retries, redirects, and rate limiting.

To manage these settings, configure the following fields while editing or creating an API connector:

Test an API connector

When creating an API connector in Sigma, you can test the connector to ensure it is configured correctly and returns the expected response.

1. After following the steps to create a new API connector in Sigma, but before clicking Save, click Test connector.
2. In the Test connector modal, enter values for any dynamic parameters in Request headers, Query parameters, Path parameters, or the Request body.
3. (Optional) Turn on the Dry run toggle to compile and review the request without sending it.
4. Click Test.
5. Review the response in the Test results section.
6. Click Close.

Grant access to API credentials and connectors

To grant users and teams access to use API credentials and connectors:

1. Go to Administration > API connectors.
   1. From the Sigma header, click your user avatar to open the user menu.
   2. Select Administration to open the Administration portal.
   3. From the side panel, select API connectors.
2. Select the Credentials or Connectors tab.
3. Select the credentials or connectors you want to manage.
4. Click Permissions.
5. In the Grant access to modal, search for and select the users or teams to grant access to.
6. Under Access, select the access to grant to each user or team.
7. (Optional) To notify users when granting access, select the Send email checkbox.
8. (Optional) If you checked the Send email checkbox, enter a message in the Add a message field.
9. Click Share.

API connector and credential permissions matrix

The following table details the minimum document, account, connector, and credential permissions required for several common use cases involving API actions. For example, to trigger an action sequence with a Call API action, a user must have Can view access to the workbook with the action sequence, an account type with the Trigger API actions permission enabled, and Can use access to the connector.

1Can use access to the credential is only required to manage the use of the credential in a connector. It is not required to edit other details of a connector.

Examples

For step-by-step tutorials on how to configure API credentials and connectors, see the following:

• Tutorial: Configure API credentials, connectors, and actions for the Sigma REST API
• Tutorial: Configure API credentials, connectors, and actions for the NYC Open Data API

Related resources

• Create actions that call API endpoints
• Configure mutual transport layer security (mTLS) in Sigma
• Tutorial: Configure API credentials, connectors, and actions for the NYC Open Data API
• Tutorial: Configure API credentials, connectors, and actions for the Sigma REST API