EmbedSigma TenantsDeploy content to tenant organizations

Programmatically deploy content from a parent organization to tenants

View as Markdown

This is a premium feature. To enable it for your Sigma organization, contact your Sigma Account Executive.

You can use the Sigma REST API to deploy content from a parent organization to one or more tenant organizations.

This document outlines the required endpoints and follows one example end-to-end. For the equivalent steps in the Sigma UI, and for details about what content gets deployed and other considerations, see Deploy content from a parent organization to one or more tenants.

An admin in the parent organization can programmatically perform the following steps. For steps that need to be performed in a tenant organization, the admin can impersonate each tenant for API calls.

Example scenario

The following steps deploy a Quarterly sales dashboard workbook from a parent organization to two tenant organizations, Acme West and Acme East. Each tenant has its own Snowflake connection that the workbook’s parent connection must be swapped to on deployment.

Steps

1

Retrieve connection information

For the parent organization and each target tenant, retrieve the connection ID and name information. Use List connections (GET /v2/connections).

In this example, the parent organization’s connection list includes Snowflake Example:

Response
1{
2  "entries": [
3    {
4      "organizationId": "2f6b8e4a-9c1d-4b7a-8e2c-6d3f9a1b5c7e",
5      "connectionId": "9f2a6b1e-4c3d-4a8f-9e21-6d7c8b3a51f0",
6      "isSample": false,
7      "isAuditLog": false,
8      "lastActiveAt": "2026-08-20T16:42:00.000Z",
9      "name": "Snowflake Example",
10      "type": "snowflake",
11      "useOauth": false,
12      "createdBy": "qJ8VpXeRp3ZvNtLm6WkYbGjFcAoS9h",
13      "updatedBy": "qJ8VpXeRp3ZvNtLm6WkYbGjFcAoS9h",
14      "createdAt": "2024-02-11T18:05:00.000Z",
15      "updatedAt": "2026-08-20T16:42:00.000Z",
16      "isArchived": false,
17      "friendlyName": true,
18      "isIndependentOAuth": false
19    }
20  ],
21  "nextPage": null,
22  "total": 1,
23  "hasMore": false
24}

Impersonate each tenant and call the endpoint again to retrieve that tenant’s connection. In this example, the Acme West tenant’s connection list includes Snowflake - Tenant Example:

Response
1{
2  "entries": [
3    {
4      "organizationId": "5e9c2b7a-3f1d-4a8e-9b6c-2d4f8a1e6c3b",
5      "connectionId": "3d4e8f21-7b6c-4a9d-8e12-5f6a7b8c9d0e",
6      "isSample": false,
7      "isAuditLog": false,
8      "lastActiveAt": "2026-08-19T09:12:00.000Z",
9      "name": "Snowflake - Tenant Example",
10      "type": "snowflake",
11      "useOauth": false,
12      "createdBy": "qJ8VpXeRp3ZvNtLm6WkYbGjFcAoS9h",
13      "updatedBy": "qJ8VpXeRp3ZvNtLm6WkYbGjFcAoS9h",
14      "createdAt": "2025-06-03T14:20:00.000Z",
15      "updatedAt": "2026-08-19T09:12:00.000Z",
16      "isArchived": false,
17      "friendlyName": true,
18      "isIndependentOAuth": false
19    }
20  ],
21  "nextPage": null,
22  "total": 1,
23  "hasMore": false
24}
2

Create a user attribute

In the parent organization, create a user attribute (POST /v2/user-attributes) to hold the tenant connection to swap to.

POST
/v2/user-attributes
1curl -X POST https://api.sigmacomputing.com/v2/user-attributes \
2     -H "Authorization: Bearer <token>" \
3     -H "Content-Type: application/json" \
4     -d '{
5  "name": "tenant_snowflake_connection",
6  "description": "Connection ID of the Snowflake connection to swap to when deploying to a tenant."
7}'
Try it

The response returns a userAttributeId:

Response
1{
2  "userAttributeId": "e4b7c2a1-9d3f-4e6b-8a2c-5f1d9e3b7a4c",
3  "name": "tenant_snowflake_connection",
4  "createdBy": "qJ8VpXeRp3ZvNtLm6WkYbGjFcAoS9h",
5  "updatedBy": "qJ8VpXeRp3ZvNtLm6WkYbGjFcAoS9h",
6  "createdAt": "2026-08-20T16:45:00.000Z",
7  "updatedAt": "2026-08-20T16:45:00.000Z",
8  "description": "Connection ID of the Snowflake connection to swap to when deploying to a tenant."
9}
3

Assign the user attribute to tenants

Assign the user attribute to target tenants with the value of the relevant connection ID for each tenant. Use Set a user attribute for tenants (POST /v2/user-attributes/{userAttributeId}/tenants).

POST
/v2/user-attributes/:userAttributeId/tenants
1curl -X POST https://api.sigmacomputing.com/v2/user-attributes/userAttributeId/tenants \
2     -H "Authorization: Bearer <token>" \
3     -H "Content-Type: application/json" \
4     -d '{
5  "assignments": [
6    {
7      "tenantOrganizationId": "5e9c2b7a-3f1d-4a8e-9b6c-2d4f8a1e6c3b",
8      "value": {
9        "type": "string",
10        "val": "3d4e8f21-7b6c-4a9d-8e12-5f6a7b8c9d0e"
11      }
12    },
13    {
14      "tenantOrganizationId": "1f4a8c3e-6d2b-4e9a-8c1f-5b7d3a2e9f6c",
15      "value": {
16        "type": "string",
17        "val": "7c1b9e4a-2f5d-4b8e-9a3c-1e2f3a4b5c6d"
18      }
19    }
20  ]
21}'
Try it
4

Create a source swap policy

Create a source swap policy with a type of deployment. Provide the user attribute as the toConnection parameter.

POST
/v2/sourceSwapPolicies
1curl -X POST https://api.sigmacomputing.com/v2/sourceSwapPolicies \
2     -H "Authorization: Bearer <token>" \
3     -H "Content-Type: application/json" \
4     -d '{
5  "fromConnectionId": "9f2a6b1e-4c3d-4a8f-9e21-6d7c8b3a51f0",
6  "name": "Tenant Snowflake Swap",
7  "swaps": {
8    "deploymentSwaps": [],
9    "toConnection": {
10      "swapType": "attribute",
11      "userAttributeId": "e4b7c2a1-9d3f-4e6b-8a2c-5f1d9e3b7a4c"
12    }
13  },
14  "type": "deployment"
15}'
Try it

The response returns a policyId:

Response
1{
2  "policyId": "2a6f8b3d-5c1e-4a9b-8d3f-7e2c4b6a9f1d"
3}
5

Create a deployment policy

In the parent organization, create a deployment policy (POST /v2/deploymentPolicies). For the sourceSwapPolicies parameter in the request body, provide one or more source swap policies.

POST
/v2/deploymentPolicies
1curl -X POST https://api.sigmacomputing.com/v2/deploymentPolicies \
2     -H "Authorization: Bearer <token>" \
3     -H "Content-Type: application/json" \
4     -d '{
5  "name": "Quarterly Sales Starter Pack",
6  "sourceSwapPolicies": [
7    "2a6f8b3d-5c1e-4a9b-8d3f-7e2c4b6a9f1d"
8  ]
9}'
Try it

The response returns a deploymentPolicyId:

Response
1{
2  "deploymentPolicyId": "b8e3a7c1-4f2d-4b9e-9a6c-3d5f1e8b2a4c"
3}
6

Add documents and folders to the deployment policy

Add documents and folders to the deployment policy (POST /v2/deploymentPolicies/{deploymentPolicyId}/files).

To identify which documents to add, call the relevant endpoint and use the relevant IDs in the inodeIds option:

  • List workbooks and use the workbookId in the response.
  • List reports and use the reportId in the response.
  • List data models and use the dataModelId in the response.
  • Retrieve folder IDs with the List files (GET /v2/files) endpoint and use the relevant inodeId in the response.

You can provide up to 100 IDs per request. In this example, the Quarterly sales dashboard workbook has a workbookId of 6a1d8f3b-2e5c-4b7a-9d1e-4c8b6a3f7e2d:

POST
/v2/deploymentPolicies/:deploymentPolicyId/files
1curl -X POST https://api.sigmacomputing.com/v2/deploymentPolicies/deploymentPolicyId/files \
2     -H "Authorization: Bearer <token>" \
3     -H "Content-Type: application/json" \
4     -d '{
5  "inodeIds": [
6    "6a1d8f3b-2e5c-4b7a-9d1e-4c8b6a3f7e2d"
7  ]
8}'
Try it
7

Add tenants to the deployment policy

Add each tenant to the deployment policy (POST /v2/deploymentPolicies/{deploymentPolicyId}/tenants). Call the endpoint once per tenant:

POST
/v2/deploymentPolicies/:deploymentPolicyId/tenants
1curl -X POST https://api.sigmacomputing.com/v2/deploymentPolicies/deploymentPolicyId/tenants \
2     -H "Authorization: Bearer <token>" \
3     -H "Content-Type: application/json" \
4     -d '{
5  "tenantOrganizationId": "5e9c2b7a-3f1d-4a8e-9b6c-2d4f8a1e6c3b"
6}'
Try it
POST
/v2/deploymentPolicies/:deploymentPolicyId/tenants
1curl -X POST https://api.sigmacomputing.com/v2/deploymentPolicies/deploymentPolicyId/tenants \
2     -H "Authorization: Bearer <token>" \
3     -H "Content-Type: application/json" \
4     -d '{
5  "tenantOrganizationId": "1f4a8c3e-6d2b-4e9a-8c1f-5b7d3a2e9f6c"
6}'
Try it

After both calls succeed, Quarterly sales dashboard is deployed to both Acme West and Acme East, with each tenant’s connection swapped in for the parent connection.

You cannot retrieve the status of a deployment through the REST API. To review the status, use the Sigma UI. See Review deployment status and errors.