> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://help.sigmacomputing.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://help.sigmacomputing.com/_mcp/server.

# Configure API credentials and connectors in Sigma

> Configure API credentials and connectors in Sigma so workbook actions can call external services securely.

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](/docs/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.

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](/docs/account-type-and-license-overview) 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](#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)**
* **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:

   <table>
     <thead>
       <tr>
         <th>
           Field
         </th>

         <th>
           Description
         </th>
       </tr>
     </thead>

     <tbody>
       <tr>
         <td>
           <strong>Name</strong>
         </td>

         <td>
           The name of the credential as it appears in a connector.
         </td>
       </tr>

       <tr>
         <td>
           <strong>Description</strong>
         </td>

         <td>
           (Optional) A description that helps users identify the credential.
         </td>
       </tr>

       <tr>
         <td>
           <strong>Authorized domains</strong>
         </td>

         <td>
           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.
         </td>
       </tr>
     </tbody>
   </table>

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

<table>
  <thead>
    <tr>
      <th>
        Field
      </th>

      <th>
        Description
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <strong>Token</strong>
      </td>

      <td>
        The token used to authenticate with the API.
      </td>
    </tr>
  </tbody>
</table>

<table>
  <thead>
    <tr>
      <th>
        Field
      </th>

      <th>
        Description
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <strong>Username</strong>
      </td>

      <td>
        The username for authentication.
      </td>
    </tr>

    <tr>
      <td>
        <strong>Password</strong>
      </td>

      <td>
        The password associated with the username.
      </td>
    </tr>
  </tbody>
</table>

<table>
  <thead>
    <tr>
      <th>
        Field
      </th>

      <th>
        Description
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <strong>Key</strong>
      </td>

      <td>
        The key for authentication expected by the endpoint.
      </td>
    </tr>

    <tr>
      <td>
        <strong>Value</strong>
      </td>

      <td>
        The value for the key.
      </td>
    </tr>

    <tr>
      <td>
        <strong>Pass in as</strong>
      </td>

      <td>
        Determines whether the key and value are sent as a request 

        <strong>Header</strong>

         or as a 

        <strong>Query parameter</strong>

        .
      </td>
    </tr>
  </tbody>
</table>

<table>
  <thead>
    <tr>
      <th>
        Field
      </th>

      <th>
        Description
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <strong>Client ID</strong>
      </td>

      <td>
        The client ID for authentication.
      </td>
    </tr>

    <tr>
      <td>
        <strong>Client secret</strong>
      </td>

      <td>
        The client secret associated with the client ID.
      </td>
    </tr>

    <tr>
      <td>
        <strong>Access token URL</strong>
      </td>

      <td>
        The URL to send the client credentials to in order to receive an access token.
      </td>
    </tr>

    <tr>
      <td>
        <strong>Send client credentials as</strong>
      </td>

      <td>
        Determines whether to send client credentials as a 

        <strong>Basic auth header</strong>

         or in the request 

        <strong>Body</strong>

        .
      </td>
    </tr>

    <tr>
      <td>
        <strong>Scopes</strong>
      </td>

      <td>
        (Optional) Additional permissions requested by the OAuth provider.
      </td>
    </tr>

    <tr>
      <td>
        <strong>Token request parameters</strong>
      </td>

      <td>
        (Optional) Additional parameters provided when requesting an access token. Select 

        <strong>+ Add parameters</strong>

         to add a key-value pair, and send it in the body, header, or as a query parameter.
      </td>
    </tr>
  </tbody>
</table>

<table>
  <thead>
    <tr>
      <th>
        Field
      </th>

      <th>
        Description
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <strong>Client ID</strong>
      </td>

      <td>
        The client ID for authentication.
      </td>
    </tr>

    <tr>
      <td>
        <strong>Client secret</strong>
      </td>

      <td>
        The client secret associated with the client ID.
      </td>
    </tr>

    <tr>
      <td>
        <strong>Authorization URL</strong>
      </td>

      <td>
        The URL to send the user to in order to authenticate and receive an authorization code.
      </td>
    </tr>

    <tr>
      <td>
        <strong>Access token URL</strong>
      </td>

      <td>
        The URL to send the authorization code to in order to receive an access token.
      </td>
    </tr>

    <tr>
      <td>
        <strong>Send client credentials as</strong>
      </td>

      <td>
        Determines whether to send client credentials as a 

        <strong>Basic auth header</strong>

         or in the request 

        <strong>Body</strong>

        .
      </td>
    </tr>

    <tr>
      <td>
        <strong>Scopes</strong>
      </td>

      <td>
        (Optional) Additional permissions requested by the OAuth provider.
      </td>
    </tr>

    <tr>
      <td>
        <strong>Authorization request parameters</strong>
      </td>

      <td>
        (Optional) Additional parameters provided when requesting an authorization code. Select 

        <strong>+ Add parameters</strong>

         to add a key-value pair, and send it in the body, header, or as a query parameter.
      </td>
    </tr>

    <tr>
      <td>
        <strong>Token request parameters</strong>
      </td>

      <td>
        (Optional) Additional parameters provided when requesting an access token. Select 

        <strong>+ Add parameters</strong>

         to add a key-value pair, and send it in the body, header, or as a query parameter.
      </td>
    </tr>
  </tbody>
</table>

<table>
  <thead>
    <tr>
      <th>
        Field
      </th>

      <th>
        Description
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <strong>Client ID</strong>
      </td>

      <td>
        (Optional) The client ID for authentication.
      </td>
    </tr>

    <tr>
      <td>
        <strong>Client secret</strong>
      </td>

      <td>
        (Optional) The client secret associated with the client ID.
      </td>
    </tr>

    <tr>
      <td>
        <strong>Username</strong>
      </td>

      <td>
        The username for authentication.
      </td>
    </tr>

    <tr>
      <td>
        <strong>Password</strong>
      </td>

      <td>
        The password associated with the username.
      </td>
    </tr>

    <tr>
      <td>
        <strong>Access token URL</strong>
      </td>

      <td>
        The URL to send the user credentials to in order to receive an access token.
      </td>
    </tr>

    <tr>
      <td>
        <strong>Send client credentials as</strong>
      </td>

      <td>
        Determines whether to send client credentials as a 

        <strong>Basic auth header</strong>

         or in the request 

        <strong>Body</strong>

        .
      </td>
    </tr>

    <tr>
      <td>
        <strong>Scopes</strong>
      </td>

      <td>
        (Optional) Additional permissions requested by the OAuth provider.
      </td>
    </tr>

    <tr>
      <td>
        <strong>Token request parameters</strong>
      </td>

      <td>
        (Optional) Additional parameters provided when requesting an access token. Select 

        <strong>+ Add parameters</strong>

         to add a key-value pair, and send it in the body, header, or as a query parameter.
      </td>
    </tr>
  </tbody>
</table>

<table>
  <thead>
    <tr>
      <th>
        Field
      </th>

      <th>
        Description
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <strong>Access key ID</strong>
      </td>

      <td>
        The ID for authentication, associated with your 

        <strong>Secret access key</strong>

        .
      </td>
    </tr>

    <tr>
      <td>
        <strong>Secret access key</strong>
      </td>

      <td>
        The secret key used to sign requests.
      </td>
    </tr>

    <tr>
      <td>
        <strong>Session token</strong>
      </td>

      <td>
        (Optional) The current token used to authenticate when using temporary credentials.
      </td>
    </tr>

    <tr>
      <td>
        <strong>Region</strong>
      </td>

      <td>
        (Optional) The AWS region associated with the request. For example, 

        <code>us-east-1</code>

        . If left blank, the region is inferred from the 

        <strong>Base URL</strong>

         of the connector.
      </td>
    </tr>

    <tr>
      <td>
        <strong>Service</strong>
      </td>

      <td>
        (Optional) The AWS service name associated with the request. For example, 

        <code>s3</code>

        . If left blank, the service is inferred from the 

        <strong>Base URL</strong>

         of the connector.
      </td>
    </tr>

    <tr>
      <td>
        <strong>Temporary credentials URL</strong>
      </td>

      <td>
        (Optional) The URL used to retrieve temporary credentials.
      </td>
    </tr>

    <tr>
      <td>
        <strong>Access key field</strong>
      </td>

      <td>
        (Optional) The field name in the temporary credential response that contains the access key ID.
      </td>
    </tr>

    <tr>
      <td>
        <strong>Secret key field</strong>
      </td>

      <td>
        (Optional) The field name in the temporary credential response that contains the secret access key.
      </td>
    </tr>

    <tr>
      <td>
        <strong>Session token field</strong>
      </td>

      <td>
        (Optional) The field name in the temporary credential response that contains the session token.
      </td>
    </tr>

    <tr>
      <td>
        <strong>Expiration field</strong>
      </td>

      <td>
        (Optional) The field name in the temporary credential response that indicates when the token expires.
      </td>
    </tr>
  </tbody>
</table>

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

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).

### 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](#bearer-token)
* [Basic auth](#basic-auth)
* [API key](#api-key)
* [OAuth (client credentials)](#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.

Before creating a connector, identify an existing credential to use, or [Add a new API credential to Sigma](#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:

   | 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](#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](/docs/configure-mutual-transport-layer-security-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](#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](#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](#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](#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](#configure-governance-settings-for-an-api-connector).                                                                                                 |

4. Review the endpoint preview for accuracy.

5. (Optional) Select **Test connector** to [test the connector](#test-an-api-connector).

6. Click **Save**.

To use your API connector in a workbook, see [Create actions that call API endpoints](/docs/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:

   | 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](/docs/tutorial-configure-api-credentials-connectors-and-actions-for-the-sigma-rest-api#create-a-connector).

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 <img src="https://sigma-docs-screenshots.s3.us-west-2.amazonaws.com/Icons/add.svg" alt="" /> **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.

#### 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:

   | 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 <img src="https://sigma-docs-screenshots.s3.us-west-2.amazonaws.com/Icons/add.svg" alt="" /> **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](#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 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 configuring a dynamic value with the **Array** type, you must set a type for the array's contents. If you set the type of the array to **Object**, you must also set types for the properties of that object.

For example, to configure a connector that sends a request with a list of users, you can set a dynamic value with the type **Array**, set the type of that array's contents to **Object**, and then set the types of each property in that object (e.g. `user_id` with type **Number**).

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"`).

![An example Call API action configured with a static value of 123 on a dynamic value with the type String](https://files.buildwithfern.com/sigma.docs.buildwithfern.com/f4628c468274b111add18afa3fe02fc19582e4ab82f4204d0b8b4050c7c2c371/assets/docs-images/902b95d862c59aa192f61568b0ed096b5b73243022dccbb489aa8bb201561ed4-API_Static_Type.png)

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.

![An example Call API action configured with a formula value of 123 on a dynamic value with the type String, showing an Invalid type error](https://files.buildwithfern.com/sigma.docs.buildwithfern.com/5b742b4756c7436ce5f098ea0c8774aa3ab48f49e9a6fccf273f17b60fbd7082/assets/docs-images/f6ae894a2cbda82dff3c6d53d34b63bb31dde689a954eb4ad463fbd02dc83e78-Formula_invalid_type.png)

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 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 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 <img src="https://sigma-docs-screenshots.s3.us-west-2.amazonaws.com/Icons/add.svg" alt="" /> **Add**.

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

   | Field       | Description                                                                                                                                                                               |
   | :---------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
   | **Name**    | The name of the action variable as it appears in action sequences.                                                                                                                        |
   | **Type**    | The data type of the action variable in the workbook.                                                                                                                                     |
   | **Formula** | Define a formula to parse the response from the API connector. For example, `[response].key[0]` returns the first value of the `key` field from a response with the **Object** data type. |

   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](/docs/use-variables-in-actions).

### 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:

| Field                           | Description                                                                                                                                  |
| :------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------- |
| **Request timeout (seconds)**   | The maximum time, in seconds, before requests from this connector fail due to timeout. Set to `30` by default.                               |
| **Maximum retries**             | The maximum number of retries made per request for this connector on any **Retryable status codes**. Set to `0` by default.                  |
| **Retryable status codes**      | A comma-separated list of response status codes that trigger a retry, up to the **Maximum retries**. Set to `429, 502, 503, 504` by default. |
| **Maximum redirects**           | The maximum number of redirects before a request from this connector fails. Set to `0` by default. Only supports HTTPS redirects.            |
| **Maximum requests per minute** | The maximum number of requests that can be made per minute using this connector. Set to `60` by default.                                     |

To enhance data security, or meet the requirements of a particular platform, you can add mutual authentication to a connector. For more information, see [Configure mutual transport layer security (mTLS) in Sigma](/docs/configure-mutual-transport-layer-security-for-api-connectors-in-sigma).

### 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](#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 sends 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.

## 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 <img src="https://sigma-docs-screenshots.s3.us-west-2.amazonaws.com/Icons/share.svg" alt="" /> **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.

<table>
  <thead>
    <tr>
      <th>
        Use case
      </th>

      <th class="alt-bg-1">
        Document permission
      </th>

      <th class="alt-bg-1">
        Account permission
      </th>

      <th class="alt-bg-1">
        Connector permission
      </th>

      <th class="alt-bg-1">
        Credential permission
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <p>Trigger an action sequence with a Call API action</p>
      </td>

      <td>
        Can view
      </td>

      <td>
        Trigger API actions
      </td>

      <td>
        Can use
      </td>

      <td>
        None
      </td>
    </tr>

    <tr>
      <td>
        <p>Edit a Call API action</p>
      </td>

      <td>
        Can explore
      </td>

      <td>
        Create API actions
      </td>

      <td>
        Can use
      </td>

      <td>
        None
      </td>
    </tr>

    <tr>
      <td>
        <p>Create a Call API action</p>
      </td>

      <td>
        Can explore
      </td>

      <td>
        Create API actions
      </td>

      <td>
        Can use
      </td>

      <td>
        None
      </td>
    </tr>

    <tr>
      <td>
        <p>View details of an API credential</p>
      </td>

      <td>
        None
      </td>

      <td>
        Manage API connectors
      </td>

      <td>
        None
      </td>

      <td>
        Can view
      </td>
    </tr>

    <tr>
      <td>
        <p>View details of an API connector</p>
      </td>

      <td>
        None
      </td>

      <td>
        Manage API connectors
      </td>

      <td>
        Can use
      </td>

      <td>
        None
      </td>
    </tr>

    <tr>
      <td>
        <p>Edit an API connector</p>
      </td>

      <td>
        None
      </td>

      <td>
        Manage API connectors
      </td>

      <td>
        Can edit
      </td>

      <td>
        Can view

        <sup>1</sup>
      </td>
    </tr>

    <tr>
      <td>
        <p>Edit an API credential</p>
      </td>

      <td>
        None
      </td>

      <td>
        Manage API connectors
      </td>

      <td>
        None
      </td>

      <td>
        Can edit
      </td>
    </tr>

    <tr>
      <td>
        <p>Create a new API connector</p>
      </td>

      <td>
        None
      </td>

      <td>
        Manage API connectors
      </td>

      <td>
        None
      </td>

      <td>
        Can view

        <sup>1</sup>
      </td>
    </tr>

    <tr>
      <td>
        <p>Create a new API credential</p>
      </td>

      <td>
        None
      </td>

      <td>
        Manage API connectors
      </td>

      <td>
        None
      </td>

      <td>
        None
      </td>
    </tr>
  </tbody>
</table>

<p class="footnote">
  1

  **Can view** access to the credential is only required to manage the use of the credential in a connector. They are not required to edit other details of a connector.
</p>

## 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](/docs/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](/docs/tutorial-configure-api-credentials-connectors-and-actions-for-the-nyc-open-data-api)

## Related resources

* [Create actions that call API endpoints](/docs/create-actions-that-call-api-endpoints)
* [Configure mutual transport layer security (mTLS) in Sigma](/docs/configure-mutual-transport-layer-security-in-sigma)
* [Tutorial: Configure API credentials, connectors, and actions for the NYC Open Data API](/docs/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](/docs/tutorial-configure-api-credentials-connectors-and-actions-for-the-sigma-rest-api)