To securely authenticate to the Sigma REST API, you must first generate client credentials. The client ID identifies the application or user making the request, and the client secret verifies that the application or user is authorized to use the Sigma REST API.

A developer can use the client credentials to generate a bearer token to authorize access to the Sigma API. If a request doesn't include a valid token, the API response returns an error.

The Sigma REST API also supports the use of OAuth override tokens in API calls. For more information, see Use OAuth override tokens.

API client credential security

API client credentials are associated with a specific organization member. When API requests are performed using a token generated with those credentials, the API response only returns data accessible to the authenticated user and permitted for their account type.

For security purposes, do not share API credentials for a user account with individuals that have fewer access permissions than those associated with the API credentials. For example, if you create API credentials with a user that has the Admin account type, do not share those credentials with users that have an account type with fewer permissions.

You can revoke credentials at any time. If you revoke credentials, update all applications and configurations that used the revoked credentials with new credentials.

User requirements

To generate API client credentials, you must be assigned the Admin account type.

Generate API client credentials

🚩
After you create the client credentials, you cannot view the client secret again in Sigma.

You can generate API client credentials programmatically using the Sigma REST API with the Create API credentials (POST /v2/credentials) endpoint, or use the Sigma UI.

To generate API client credentials in the Sigma UI:

From Sigma Home, open Administration, or click your user avatar to open the user menu and select Administration.
In the side panel, select Developer access.

💡
Your API base URL is shown at the top of the page. Use that URL when sending requests to the Sigma REST API.
Click Create new to set up new credentials.

The Create client credentials modal opens.
For Select scopes, select the checkbox for REST API to allow these credentials to be used for the API.
For Name, enter a unique name to identify the credentials. For example, "Web app service account credentials".
[optional] For Description, enter a description of purpose of the credentials. For example, "Inventory data entry web application API requests."
For Owner, search for and select a member of your organization with whom to associate the credentials. Calls to the API use the account type permissions assigned to this user.
Click Create to generate the credentials.
Copy the client ID and secret and securely store them for future reference.

🚩
You cannot access the client secret after closing the dialog.

Use client credentials to generate an access token

After generating credentials, you can use the Sigma authentication endpoint /v2/auth/token to generate an access token. The access token is used in the request header of your API requests to authenticate to your Sigma organization.

Identify the base URL for your Sigma environment. For more information, see Identify your API request URL.
Obtain the client ID and secret you generated in Generate API client credentials.
Make a POST request to the authentication endpoint like the following:

Authentication request format

curl --request POST \
     --url <base_url>/v2/auth/token \
     --header 'content-type: application/x-www-form-urlencoded' \
     --data grant_type=client_credentials \
     --data client_id=<client_id> \
     --data client_secret=<client_secret>

💡
This example shows how to make a POST request to the authentication endpoint from the terminal. You can also use tools like Postman to make the request, and to manage variables like your client_id, client_secret, and base_url. For step-by-step instructions on using Postman with the Sigma API, see Sigma API with Postman.

The response includes an access token that you can use to authenticate your requests to the API. The access token is valid for 1 hour. After 1 hour, you must refresh your existing token or generate a new one.

The response body includes the access token, a refresh token, the token type, and the number of seconds until the access token expires, in the following format:

Authentication response format

{
    "access_token":"<access_token>",
    "refresh_token":"<refresh_token>",
    "token_type":"bearer",
    "expires_in":3599
}

Revoke API client credentials

If you lose your API client credentials, or they become compromised, you can revoke the credentials.

You can revoke API client credentials programmatically using the Sigma REST API with the Delete API credentials (DELETE /v2/credentials/{clientId}) endpoint, or use the Sigma UI.

To revoke API client credentials in the Sigma UI:

Go to Administration > Developer access:
1. In the Sigma header, click your user avatar to open the user menu.
2. Select Administration to open the Administration portal.
3. In the side panel, select Developer access.
In the list of credentials, locate the one you want to regenerate, then click More and select Revoke.