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 are not able to configure a Call API action in a workbook.

Every API connector in Sigma is associated with a specific 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, Sigma’s, or that of a third party. 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.

📘

Any user with access to the credential and an account type with the Manage API connectors permission enabled can use the credential when creating new connectors. See Create a new API connector in Sigma.

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)

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 fields to define the credential:

🚧

Secrets like tokens, passwords, and API secret keys are encrypted, and are never returned to any user in the Sigma UI.

5. 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 each authentication method is 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 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. 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 connector, 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.

💡

Before creating a connector, identify an existing credential to use, or Add a new API credential to Sigma for that API.

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:

4. Review the endpoint preview for accuracy.
5. (Optionally) 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.
   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, 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:

💡

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.

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:

📘

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.

Configure a request body as form-data

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:

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 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 using the connector 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. After entering a dynamic value, navigate to the Type dropdown and select the type to apply. You can select one of the following types:

• Text
• Number
• Logical
• Array
• Object

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 like 123, it is converted to a string like "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 like 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.

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.

📘

When the Dry run toggle is on, Sigma shows you the compiled request that Sigma will send to the API endpoint without sending it. This can be used to review the method, URL, headers, and body of the request without incurring any costs associated with sending an actual request. To test the request and receive a response from the API endpoint, turn off the Dry run toggle.

Create custom action variables for an API connector

When creating an API connector in Sigma, you can parse the response from an API connector to create custom action variables.

These action variables are then available to use in workbook action sequences that use the API connector in a Call API action. 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. This allows you to more easily incorporate the results of a Call API action in your action sequence.

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:

💡

Consider the data type of the response and the desired data type of the response variable when configuring the Type and Formula. 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 Type, and use a formula 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.

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 view access to the credential are only required to manage the use of the credential in a connector. They are 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