Create connection
- OpenAPI 3.1.0 document: https://api.rollstack.com/public/v1/openapi.json
- The whole reference in Markdown: https://docs.rollstack.com/llms-full.txt
- An index of the reference: https://docs.rollstack.com/llms.txt
POST https://api.rollstack.com/public/v1/connections
Creates a data source connection after testing its credentials. Only owners and admins of the organization may. Snowflake, Databricks and BigQuery connections are created only in the app.
Requires the connections:write scope.
Operation ID: createConnection.
Headers
Idempotency-Key(string): A unique value, such as a UUID, that makes retrying this call safe. A retry with the same key within 24 hours answers the first call's result instead of running it again. Use a new key for each new call. From 1 to 255 printable ASCII characters.
Request body, required
application/json
- When
typeisTableaubaseUrl(string, required): The URL of the Tableau Cloud or Server instance the connection reads from. It can't change when replacing credentials: send the connection's currentconfig.baseUrl, or create a new connection for another instance. Trailing slashes are removed. Example:https://acme.online.tableau.com.type(Tableau, required): Set toTableauto connect Tableau Cloud or Tableau Server. When replacing credentials, it must match thetypein the path.siteName(string or null): The Tableau site the connection reads from, as your Tableau URLs name it after#/site/(acmeinhttps://online.tableau.com/#/site/acme/workbooks).nullfor a Tableau Server's default site, which is also what omitting it means when creating the connection. It can't change when replacing credentials: omit it or send the connection's currentconfig.siteName. Example:acme.clientId(string, required): The Client ID of the Tableau connected app Rollstack signs in through. In Tableau, create it under Settings > Connected Apps > New Connected App > Direct Trust, with access to all projects and all domains allowed, then enable it. Example:0f8e1c2d-3b4a-4c5d-9e6f-7a8b9c0d1e2f.secretId(string, required): The Secret ID of the connected app's secret, shown with its Client ID under Settings > Connected Apps in Tableau. Example:5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d.secretValue(string, required): The Secret Value of the same connected app secret assecretId. Example:your-connected-app-secret.username(string, required): Your Tableau username, usually your email: the connected app signs in to Tableau as this user, and Rollstack tests the credentials with it. When the connection is created, your access uses it, and each other member who gets access is given a username derived from their Rollstack email in the same pattern, such as their email if this is yours. Members can change theirs in the app. Example:jane@acme.com.name(string, required): The name members will see for the connection in Rollstack. Example:Acme Looker.autoProvision(boolean): Whether everyone in the organization gets access to the connection: every active member right away, and each new member as they join. Whenfalse, only you get access, and you add others withaddConnectionUsers. Defaults totrue.
- When
typeisLookerbaseUrl(string, required): The URL of the Looker instance the connection reads from. It can't change when replacing credentials: send the connection's currentconfig.baseUrl, or create a new connection for another instance. Trailing slashes are removed. Example:https://acme.cloud.looker.com.type(Looker, required): Set toLookerto connect a Looker instance. When replacing credentials, it must match thetypein the path.clientId(string, required): The client ID of the Looker API key Rollstack connects with. A Looker admin generates it under Admin > Users > Users: open the user or service account, then Edit keys under API keys. Withimpersonatedauthorization, that Looker user must have the Admin role. Example:kG8mQ2xYp4Rz7wNs3Vbc.clientSecret(string, required): The client secret generated withclientId, from the same Looker API key. Example:your-looker-client-secret.embedSecret(string, required): The embed secret Rollstack signs Looker embed URLs with to open your dashboards. Generate it on the Embed page of Looker's Admin panel, where you also addhttps://*.rollstack.comto the Embedded Domain Allowlist. Example:your-looker-embed-secret.embeddingMode(string, required): How Rollstack opens your Looker dashboards to capture their charts.signed(recommended): through embed URLs signed withembedSecret.private: through Looker's API, by exporting dashboards as PDFs, which is slower and less reliable.cookielesscurrently works likesigned. One ofsigned,cookieless,private.authorizationMode(string): Whose Looker permissions apply when members read data through the connection.per_user: each member reads with an API key of their own Looker user, so they see what their Looker permissions allow; every member needs their own API key set up.impersonated: this API key, whose Looker user must have the Admin role, acts as each member's Looker user, found by their email.shared: everyone reads with this API key and its permissions. Defaults toper_userwhen creating the connection. Changing it overwrites every member's Looker credentials, which can't be undone. When replacing credentials, omitting it keeps the connection's current value. One ofper_user,impersonated,shared.lookerUserEmail(string or null): Withimpersonatedauthorization, the email of the Looker user this API key acts as when Rollstack tests the credentials, usually your own; the test fails unless this orlookerUserIdfinds a Looker user. When members read data, each acts as the Looker user with their own email instead. When replacing credentials, omitting it keeps the connection's current value. Example:jane@acme.com.lookerUserId(string or null): Withimpersonatedauthorization, the id of the Looker user this API key acts as when Rollstack tests the credentials. When there's none, Rollstack finds it fromlookerUserEmail. When replacing credentials, omitting it keeps the connection's current value. Example:42.userAttributes(object): Looker user attributes, by attribute name, that Rollstack sets for every member when it opens dashboards through signed embed URLs, such as aregionyour Looker models filter rows by. They take precedence over the Looker user's own values for those attributes. If omitted when creating the connection, none are set. When replacing credentials, omitting it keeps the connection's current value. Example:{"region":"EMEA"}.name(string, required): The name members will see for the connection in Rollstack. Example:Acme Looker.autoProvision(boolean): Whether everyone in the organization gets access to the connection: every active member right away, and each new member as they join. Whenfalse, only you get access, and you add others withaddConnectionUsers. Defaults totrue.
- When
typeisLightdashbaseUrl(string, required): The URL of the Lightdash instance the connection reads from. It can't change when replacing credentials: send the connection's currentconfig.baseUrl, or create a new connection for another instance. Trailing slashes are removed. Example:https://acme.lightdash.cloud.personalAccessToken(string, required): The Lightdash token Rollstack connects with: a personal access token, starting withldpat_, or a service account token, starting withldsvc_. When the connection is created, your access uses it; every other member sets their own token in the app. Example:ldpat_your-personal-access-token.userEmail(string or null): The email of the Lightdash user whose user attributes Rollstack applies when it opens dashboards through your access. Only used with a service account token (ldsvc_); when it's set, the token must have Lightdash's Admin role, or the test fails. Ifnull, the attributes of the token's own user apply. When the connection is created, only your access gets it: other members' access applies the attributes of their own token's user. When replacing credentials, omitting it keeps the connection's current value. Example:jane@acme.com.projectId(string, required): The ID of the Lightdash project whose dashboards the connection reads, shown at the bottom of the Project Settings page in Lightdash. Example:3e5f7a9b-1c2d-4e3f-8a5b-7c9d1e3f5a7b.embedSecret(string, required): The embed secret Rollstack signs Lightdash embed tokens with to open your dashboards. Generate it in Lightdash under Project Settings > Embed Configuration. Example:your-lightdash-embed-secret.type(Lightdash, required): Set toLightdashto connect a Lightdash project. When replacing credentials, it must match thetypein the path.name(string, required): The name members will see for the connection in Rollstack. Example:Acme Looker.autoProvision(boolean): Whether everyone in the organization gets access to the connection: every active member right away, and each new member as they join. Whenfalse, only you get access, and you add others withaddConnectionUsers. Defaults totrue.
- When
typeisMetabasebaseUrl(string, required): The URL of the Metabase instance the connection reads from. It can't change when replacing credentials: send the connection's currentconfig.baseUrl, or create a new connection for another instance. Trailing slashes are removed. Example:https://acme.metabaseapp.com.embedSecret(string, required): The embedding secret key Rollstack signs Metabase embed URLs with to open your dashboards. In Metabase's Admin settings, go to Embedding, enable embedding, then generate the Embedding Secret Key under More details. Example:your-metabase-embedding-secret.authMethod(string, required): How Rollstack signs in to Metabase.apiKey(recommended): with the admin API key inapiKey, matching each member to the Metabase user with their email, so they only see the dashboards their Metabase permissions allow.password: each member signs in with their own Metabase username and password; members other than you enter their password in the app. One ofpassword,apiKey.type(Metabase, required): Set toMetabaseto connect a Metabase instance. When replacing credentials, it must match thetypein the path.username(string, required): Your Metabase username, usually your email. Withpasswordauth, Rollstack signs in with it andpassword; withapiKeyauth, it finds your Metabase user, whose permissions apply. When the connection is created, your access uses it, and each other member who gets access is given a username derived from their Rollstack email in the same pattern. Example:jane@acme.com.password(string or null): Your Metabase password, required withpasswordauth. When the connection is created, only your access gets it: other members enter their own in the app. Defaults tonull. Example:your-metabase-password.apiKey(string or null): The admin API key Rollstack reads Metabase with, required withapiKeyauth. Every member's access uses it. Defaults tonull. Example:mb_your-api-key.sessionId(string or null): Withpasswordauth, an existing Metabase session token for Rollstack to use. If omitted, Rollstack signs in withusernameandpasswordto get one, and again whenever it stops working. Defaults tonull. Example:8c1d3e5f-7a9b-4c1d-8e3f-5a7b9c1d3e5f.name(string, required): The name members will see for the connection in Rollstack. Example:Acme Looker.autoProvision(boolean): Whether everyone in the organization gets access to the connection: every active member right away, and each new member as they join. Whenfalse, only you get access, and you add others withaddConnectionUsers. Defaults totrue.
- When
typeisSalesforcetype(Salesforce, required): Set toSalesforceto connect a Salesforce org. When replacing credentials, it must match thetypein the path.baseUrl(string, required): The URL of the Salesforce instance the connection reads from. It can't change when replacing credentials: send the connection's currentconfig.baseUrl, or create a new connection for another instance. Trailing slashes are removed. Example:https://acme.my.salesforce.com.clientId(string, required): The Consumer Key of the External Client App you create for Rollstack in Salesforce. Enable the JWT Bearer Flow on it and upload Rollstack's certificate, which you can download from the Salesforce connection setup in the Rollstack app. Find the key in the External Client App's Settings tab, under OAuth Settings > Consumer Key and Secret. Example:your-consumer-key.username(string, required): Your Salesforce username: Rollstack signs in to Salesforce as this user through the JWT Bearer Flow, and tests the credentials with it. When the connection is created, your access uses it, and each other member who gets access is given a username derived from their Rollstack email in the same pattern. Example:jane@acme.com.useCrma(boolean, required): Whether you can also add CRM Analytics dashboards from this connection to Rollstack reports, besides Salesforce reports. Whenfalse, only Salesforce reports are offered.name(string, required): The name members will see for the connection in Rollstack. Example:Acme Looker.autoProvision(boolean): Whether everyone in the organization gets access to the connection: every active member right away, and each new member as they join. Whenfalse, only you get access, and you add others withaddConnectionUsers. Defaults totrue.
- When
typeisPowerBIclientId(string, required): The Application (client) ID of the Microsoft Entra app registration Rollstack reads Power BI through, shown on its Overview page in the Azure Portal. Add the app to each Power BI workspace Rollstack should read, with the Member role. Example:2b4d6f8a-0c1e-4a3b-9d5f-7b9d1f3a5c7e.tenantId(string, required): The Directory (tenant) ID of your Microsoft Entra tenant, shown next to the Application ID on the app registration's Overview page. Example:4d6f8a0c-2e3a-4b5c-8d7e-9f1a3b5c7d9e.secretValue(string, required): The Value of a client secret of the app registration, created in the Azure Portal under Certificates & secrets > New client secret. Example:your-client-secret-value.userEmail(string or null): Your email in Power BI, used withper_userauthorization: your access to the connection then shows only the Power BI reports this account can see, and each other member's access only those their own Power BI account, found by their Rollstack email, can see. Ifnullor omitted when creating the connection, no member's Power BI permissions apply, even withper_user: everyone sees what the app registration can see. Replacing it later only affects members who get access afterward. When replacing credentials, omitting it keeps the connection's current value. Example:jane@acme.com.authorizationMode(string, required): Whose Power BI permissions apply.per_user: each member only sees the Power BI reports their own Power BI account can access, found by their email, as long asuserEmailis set; the app registration needs read-only Admin API access.shared: every member sees everything the app registration can see, whatever their Power BI permissions. One ofshared,per_user.type(PowerBI, required): Set toPowerBIto connect Power BI. When replacing credentials, it must match thetypein the path.name(string, required): The name members will see for the connection in Rollstack. Example:Acme Looker.autoProvision(boolean): Whether everyone in the organization gets access to the connection: every active member right away, and each new member as they join. Whenfalse, only you get access, and you add others withaddConnectionUsers. Defaults totrue.
- When
typeisOmniinstanceSlug(string, required): Your Omni account name, the subdomain of your Omni URL (acmeinhttps://acme.omniapp.co). It can't change when replacing credentials: send the connection's currentconfig.instanceSlug. Example:acme.externalUserEmail(string, required): The email of your Omni user, usually your own email; the test fails unless an Omni user has it. When the connection is created, your access opens dashboards as this Omni user, with that user's groups, user attributes and dashboards, and each other member's access as the Omni user with their Rollstack email. Example:jane@acme.com.apiKey(string, required): An Omni organization API key, which every member's access uses. In Omni, go to Settings > API Access > Organization keys and click Generate New Key. Example:your-omni-api-key.embedSecret(string, required): The embed secret Rollstack signs Omni embed URLs with to open your dashboards. In Omni, find it under Settings > Embed > Admin; if there's no Embed section, ask Omni support to enable it. Example:your-omni-embed-secret.type(Omni, required): Set toOmnito connect an Omni account. When replacing credentials, it must match thetypein the path.name(string, required): The name members will see for the connection in Rollstack. Example:Acme Looker.autoProvision(boolean): Whether everyone in the organization gets access to the connection: every active member right away, and each new member as they join. Whenfalse, only you get access, and you add others withaddConnectionUsers. Defaults totrue.
- When
typeisSigmabaseUrl(string, required): The API base URL of your Sigma organization, which depends on the cloud and region it runs in. In Sigma, find it under Administration > Developer access. It can't change when replacing credentials: send the connection's currentconfig.baseUrl. One ofhttps://aws-api.sigmacomputing.com,https://api.us-a.aws.sigmacomputing.com,https://api.ca.aws.sigmacomputing.com,https://api.eu.aws.sigmacomputing.com,https://api.ch.aws.sigmacomputing.com,https://api.uk.aws.sigmacomputing.com,https://api.au.aws.sigmacomputing.com,https://api.in.aws.sigmacomputing.com,https://api.us.azure.sigmacomputing.com,https://api.eu.azure.sigmacomputing.com,https://api.ca.azure.sigmacomputing.com,https://api.uk.azure.sigmacomputing.com,https://api.au.azure.sigmacomputing.com,https://api.sigmacomputing.com,https://api.sa.gcp.sigmacomputing.com. Example:https://aws-api.sigmacomputing.com.organizationSlug(string, required): Your Sigma organization, as your Sigma URLs name it afterapp.sigmacomputing.com/(acmeinhttps://app.sigmacomputing.com/acme/workbook/...). Any Sigma URL of the organization works too. It can't change when replacing credentials: send the connection's currentconfig.organizationSlug. Example:acme.serviceClientId(string, required): The client ID of Sigma client credentials with the REST API and Embedding scopes, which every member's access uses. The Embedding scope is part of Sigma's secure embedding add-on. Their owner must be an active Sigma Admin. In Sigma, go to Administration > Developer access and click Create new. Example:your-sigma-client-id.serviceClientSecret(string, required): The client secret Sigma shows once, when it creates the client credentials. Rollstack stores it encrypted and never returns it. Example:your-sigma-client-secret.externalUserEmail(string, required): The email of your Sigma member, usually your own email; the test fails unless a Sigma member has it. When the connection is created, your access opens workbooks as this Sigma member, and each other member's access as the Sigma member with their Rollstack email. Example:jane@acme.com.type(Sigma, required): Set toSigmato connect a Sigma organization. When replacing credentials, it must match thetypein the path.name(string, required): The name members will see for the connection in Rollstack. Example:Acme Looker.autoProvision(boolean): Whether everyone in the organization gets access to the connection: every active member right away, and each new member as they join. Whenfalse, only you get access, and you add others withaddConnectionUsers. Defaults totrue.
- Option 9: Not supported: Snowflake, Databricks and BigQuery connections are created, and their credentials changed, only in the Rollstack app. A request with any of these types returns a
400error.type(string, required):Snowflake,DatabricksorBigQuery. Create these connections, and change their credentials, in the Rollstack app. One ofSnowflake,Databricks,BigQuery.
Response 201
Success
application/json
id(string, required): Unique identifier for the connection. Pass it withtypeto the other/connections/{type}/{id}endpoints.type(string, required): The data source the connection reads from:Tableau,Looker,Metabase,PowerBI,Lightdash,Omni,SigmaorSalesforce, or theSnowflake,DatabricksorBigQuerydata warehouse. Endpoints that act on a connection take it in their path, with the connection'sid. One ofTableau,Looker,Metabase,PowerBI,Lightdash,Omni,Sigma,Salesforce,Snowflake,Databricks,BigQuery.name(string, required): The connection's name, as members see it in Rollstack.config(object, required): The connection's settings other than its credentials, which Rollstack never returns. Each type has only the settings that apply to it.baseUrl(string): The URL of the instance the connection reads from, such as your Looker, Metabase or Snowflake URL. For Sigma, the API base URL of your Sigma organization's region. Power BI and Omni connections have none: an Omni connection's account is ininstanceSlug.siteName(string or null): Tableau only: the Tableau site the connection reads from, as your Tableau URLs name it after#/site/.nullfor a Tableau Server's default site.instanceSlug(string): Omni only: your Omni account name, the subdomain of your Omni URL (acmeinhttps://acme.omniapp.co).organizationSlug(string): Sigma only: your Sigma organization, as your Sigma URLs name it afterapp.sigmacomputing.com/(acmeinhttps://app.sigmacomputing.com/acme).projectId(string): Lightdash only: the ID of the Lightdash project whose dashboards the connection reads.embeddingMode(string): Looker only: how Rollstack opens the connection's Looker dashboards to capture their charts.signed: through embed URLs signed with the connection's embed secret.private: through Looker's API, by exporting dashboards as PDFs, which is slower and less reliable.cookielesscurrently works likesigned. One ofsigned,cookieless,private.authorizationMode(string): Looker, Power BI and Sigma only: whose permissions in the tool apply when members read data.per_user: each member's own, through their own API key in Looker or found by their email in Power BI, if the connection was created with a Power BI email.impersonated(Looker only): one admin API key acts as each member's Looker user, found by their email.shared: everyone gets the same access, that of the connection's API key in Looker or of the app registration in Power BI. Sigma:internal, each member's own Sigma account, found by their email;embed_users, the same, else an embed user Rollstack creates with the account type and teams set in the app.authMethod(string): Metabase, Snowflake, Databricks and BigQuery only: how Rollstack signs in. For Metabase,apiKeyuses an admin API key and applies each member's Metabase permissions, found by their email, whilepasswordsigns each member in with their own Metabase password. For Snowflake, Databricks and BigQuery,oauthhas each member connect their own account through a browser sign-in, whileservicehas everyone read through one Snowflake service user, with a key pair, one Databricks service principal or one Google Cloud service account.
autoProvision(boolean, required): Whether members who join the organization get access to the connection automatically. Whenfalse, its owner and admins add members withaddConnectionUsers.isActive(boolean, required): Whether at least one member's access to the connection works, so data can be read through it.falsewhen none does: for example, members still have to enter their own credentials in the app, no user in the tool has their email, or their credentials were found invalid.defaultUserId(number or null, required): The user id of the connection's default user, which the app calls its service account. Everyone with access to the connection reads its data through this member's access instead of their own.nullwhen there's none, so each member reads with their own access.owner(object or null, required): The member who owns the connection, usually the one who created it. Only the owner can delete the connection and add or remove its admins.nullif no member holds the owner role.id(number, required): The owner's user id, aslistMembersreturns it.email(string, required): The owner's email address.
admins(array of object, required): The members who manage the connection, each with their role on it: its owner and its admins.userId(number, required): The member's user id, aslistMembersreturns it.role(string, required): The member's role on the connection.owner: owns the connection; only they can delete it and add or remove admins.admin: can change the connection's settings and credentials, and manage who has access to it. One ofowner,admin.
hasCredentials(true, required): Alwaystrue. Credentials are write-only: Rollstack never returns them. Change them withreplaceConnectionCredentials.createdAt(string (date-time), required): When the connection was created.updatedAt(string (date-time), required): When the connection was last updated, for example renamed or given new credentials.