Tutorial: Configure API credentials, connectors, and actions for the Sigma REST API

By following this tutorial, you can configure an API credential and connector that allow you to call the Sigma REST API to create a team in Sigma.

User requirements

• You must be assigned an account type with the Manage API connectors permission enabled.

Configure API credentials and connectors for the Sigma REST API

This section describes how to configure an API credential and connector for the Sigma REST API.

Setup and background

To follow along with this example, you must first generate Sigma API client credentials or be provided REST API credentials by a user assigned the Admin account type in Sigma. You must use these credentials to create an API credential in Sigma. The API credential can then be used by your API connector.

Create a credential

Create an API credential in Sigma to store your Sigma API client credentials, and to use when creating an API 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. Select the Credentials tab.
3. Click Create credential.

4. In the New credential screen, configure the following fields to define the credential:

   Field	Value
   Name	Sigma client credentials
   Description	For use with the Sigma REST API.
   Authorized domains	Enter *.
   Authentication method	Select OAuth (client credentials). For Client ID, enter the Sigma API client ID you created during setup. For Client secret, enter the Sigma API client secret you created during setup. For Access token URL, enter your Sigma API base URL with /v2/auth/token appended. For example: https://api.sigmacomputing.com/v2/auth/token. For Send client credentials as, select Basic auth header.

5. Click Save.

Add the Sigma OpenAPI specification

To quickly create a connector for the Sigma REST API, you can import the Sigma OpenAPI specification. The specification defines the available endpoints and their required parameters.

📘

Sigma maintains the most recent version of the OpenAPI specification for you to download. For more information, see Get started with the Sigma REST API.

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:

   Field	Value
   Name	Sigma
   Specification URL	https://help.sigmacomputing.com/openapi/sigma-computing-public-rest-api.json

7. Click Create.

The Sigma OpenAPI specification is imported.

Create a connector

Using the credential and the Sigma OpenAPI specification you created in the previous sections, create a connector to use in workbook actions.

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. In the New API connector screen, configure the following fields to define the connector:

   Field	Value
   Name	Create Sigma team
   Description	OAuth connector for creating a team in Sigma
   Authentication credential	Select Sigma client credentials
   Connector type	Select via OpenAPI, and then select the Sigma specification you imported in the previous section. Select the correct API request URL. Open the Select endpoint dropdown and select the POST request for /v2/teams.
   Base URL	After selecting the endpoint, the Base URL is automatically populated.
   Request headers	After selecting the endpoint, the Request headers are automatically populated.
   Query parameters	Do not configure any query parameters.
   Path parameters	Do not configure any path parameters.
   Request body	Modify the request body to the following: {"name": {{team-name}},"description": {{team-description}},"members": [],"createTeamFolder": false,"visibility": "private"}
   Body parameters	For team-name and team-description, set the Type to Text.

4. Review the endpoint preview for accuracy.

5. Click Save.

Configure dynamic parameters for a POST request

You can configure dynamic parameters for the request body of a POST request, allowing users to provide dynamic inputs to the request body from within the workbook.

After following this example, you can configure actions in a workbook that call the Sigma REST API to create a team in Sigma using dynamic parameters for the request body.

Setup

To follow along with this example step-by-step, you first need to configure an API credential and connector as described in Configure API credentials and connectors for the Sigma REST API.

Configure workbook elements

In a new workbook page, add and configure the following elements:

1. From the Add element bar, select UI, and then Button.

2. From the Add element bar, select Controls, and then Text Input.

3. From the Add element bar, select Controls, and then Text Input.

4. From the Add element bar, select Controls, and then Text Area.

5. Select the first text input element. In the editor panel, configure it with the following settings:

   1. Rename the control Enter team name
   2. Set the Control ID to team-name

6. Select the second text input element. In the editor panel, configure it with the following settings:

   1. Rename the control Enter team description
   2. Set the Control ID to team-description

7. Select the text area element. In the editor panel, configure it with the following settings:

   1. Rename the control Response body
   2. Set the Control ID to response-body

8. Select the button element. In the editor panel, configure it with the following settings:

   1. Under Properties, set Text to Create team
   2. Under Actions, click Add action to add a new action to the Action sequence triggered On click

9. Configure the first action in the action sequence to call the API connector:

   Action	Select Call API
   API	Select Create Sigma team
   team-name	Set the dynamic parameter based on a Control and select the Enter team name control.
   team-description	Set the dynamic parameter based on a Control and select the Enter team description control.

10. Click Add action to add a second action to the action sequence.

11. Configure the second action in the action sequence to display the response body in the text area control:

    Action	Select Set control value
    Update control	Select Response body
    Set value as	Select Action variable and then select the response data from Call API

12. To test the API action, enter a team name and description in the corresponding controls, then click the button to trigger the Call API action. The response body populates in the text area control. If the team is created successfully, the response body contains the team ID and other details of the created team.

This example uses Sigma’s REST API to create a team, but you can use the same approach to call any API endpoint with dynamic parameters from the workbook.