Skip to main content

Replace credentials

PUT https://api.rollstack.com/public/v1/connections/{type}/{id}/credentials

Replaces every credential of a connection, after testing them. Its users' access gets the new credentials too. The instance (baseUrl, siteName, instanceSlug, organizationSlug) can't change; siteName can be left out to keep the stored site. Settings the connection doesn't show (Looker user and attributes, userEmail) keep their value when left out, but Omni's and Sigma's externalUserEmail must be sent. A failed test answers 422 with the provider's code and message.

Requires the credentials:write scope.

Operation ID: replaceConnectionCredentials.

Path parameters

  • type (string, required): The data source the connection reads from: Tableau, Looker, Metabase, PowerBI, Lightdash, Omni, Sigma or Salesforce, or the Snowflake, Databricks or BigQuery data warehouse. Endpoints that act on a connection take it in their path, with the connection's id. One of Tableau, Looker, Metabase, PowerBI, Lightdash, Omni, Sigma, Salesforce, Snowflake, Databricks, BigQuery.
  • id (string, required): Unique identifier for the connection, from listConnections, which also returns its type.

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 type is Tableau
    • baseUrl (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 current config.baseUrl, or create a new connection for another instance. Trailing slashes are removed. Example: https://acme.online.tableau.com.
    • type (Tableau, required): Set to Tableau to connect Tableau Cloud or Tableau Server. When replacing credentials, it must match the type in the path.
    • siteName (string or null): The Tableau site the connection reads from, as your Tableau URLs name it after #/site/ (acme in https://online.tableau.com/#/site/acme/workbooks). null for 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 current config.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 as secretId. 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.
  • When type is Looker
    • baseUrl (string, required): The URL of the Looker instance the connection reads from. It can't change when replacing credentials: send the connection's current config.baseUrl, or create a new connection for another instance. Trailing slashes are removed. Example: https://acme.cloud.looker.com.
    • type (Looker, required): Set to Looker to connect a Looker instance. When replacing credentials, it must match the type in 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. With impersonated authorization, that Looker user must have the Admin role. Example: kG8mQ2xYp4Rz7wNs3Vbc.
    • clientSecret (string, required): The client secret generated with clientId, 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 add https://*.rollstack.com to 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 with embedSecret. private: through Looker's API, by exporting dashboards as PDFs, which is slower and less reliable. cookieless currently works like signed. One of signed, 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 to per_user when 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 of per_user, impersonated, shared.
    • lookerUserEmail (string or null): With impersonated authorization, the email of the Looker user this API key acts as when Rollstack tests the credentials, usually your own; the test fails unless this or lookerUserId finds 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): With impersonated authorization, the id of the Looker user this API key acts as when Rollstack tests the credentials. When there's none, Rollstack finds it from lookerUserEmail. 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 a region your 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"}.
  • When type is Lightdash
    • baseUrl (string, required): The URL of the Lightdash instance the connection reads from. It can't change when replacing credentials: send the connection's current config.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 with ldpat_, or a service account token, starting with ldsvc_. 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. If null, 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 to Lightdash to connect a Lightdash project. When replacing credentials, it must match the type in the path.
  • When type is Metabase
    • baseUrl (string, required): The URL of the Metabase instance the connection reads from. It can't change when replacing credentials: send the connection's current config.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 in apiKey, 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 of password, apiKey.
    • type (Metabase, required): Set to Metabase to connect a Metabase instance. When replacing credentials, it must match the type in the path.
    • username (string, required): Your Metabase username, usually your email. With password auth, Rollstack signs in with it and password; with apiKey auth, 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 with password auth. When the connection is created, only your access gets it: other members enter their own in the app. Defaults to null. Example: your-metabase-password.
    • apiKey (string or null): The admin API key Rollstack reads Metabase with, required with apiKey auth. Every member's access uses it. Defaults to null. Example: mb_your-api-key.
    • sessionId (string or null): With password auth, an existing Metabase session token for Rollstack to use. If omitted, Rollstack signs in with username and password to get one, and again whenever it stops working. Defaults to null. Example: 8c1d3e5f-7a9b-4c1d-8e3f-5a7b9c1d3e5f.
  • When type is Salesforce
    • type (Salesforce, required): Set to Salesforce to connect a Salesforce org. When replacing credentials, it must match the type in 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 current config.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. When false, only Salesforce reports are offered.
  • When type is PowerBI
    • clientId (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 with per_user authorization: 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. If null or omitted when creating the connection, no member's Power BI permissions apply, even with per_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 as userEmail is 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 of shared, per_user.
    • type (PowerBI, required): Set to PowerBI to connect Power BI. When replacing credentials, it must match the type in the path.
  • When type is Omni
    • instanceSlug (string, required): Your Omni account name, the subdomain of your Omni URL (acme in https://acme.omniapp.co). It can't change when replacing credentials: send the connection's current config.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 to Omni to connect an Omni account. When replacing credentials, it must match the type in the path.
  • When type is Sigma
    • baseUrl (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 current config.baseUrl. One of https://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 after app.sigmacomputing.com/ (acme in https://app.sigmacomputing.com/acme/workbook/...). Any Sigma URL of the organization works too. It can't change when replacing credentials: send the connection's current config.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 to Sigma to connect a Sigma organization. When replacing credentials, it must match the type in the path.
  • 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 400 error.
    • type (string, required): Snowflake, Databricks or BigQuery. Create these connections, and change their credentials, in the Rollstack app. One of Snowflake, Databricks, BigQuery.

Response 204

Success, no content