Connected App Methods
Connected app-specific methods were introduced in Tableau 2021.4. Site-level external authorization server-specific methods were introduced in September 2022 for Tableau Cloud and in Tableau Server version 2024.2.
A connected app enables you to establish a trusted relationship between Tableau and any custom application. A connected app can be used to securely authenticate (SSO) your users to Tableau content embedded in a custom application or to authorize access to the REST API.
Connected app methods using direct trust
Using the connected app methods of the Tableau REST API, you can:
- Create, query, update, and delete a Tableau connected app
- Create, query, and delete the secret generated for a Tableau connected app
This functionality relates to UI elements and concepts described at:
- For Tableau Server: Configure Tableau Connected Apps to with Direct Trust(Link opens in a new window)
- For Tableau Cloud: Configure Tableau Connected Apps with Direct Trust(Link opens in a new window)
Connected app methods using OAuth 2.0 trust
As an alternative, you can register an external authorization server (EAS) to a site to establish a trust relationship.
Using the EAS-specific methods of the Tableau REST API, you can:
- Register, query, update, and delete an EAS on a site
This functionality relates to UI elements and concepts described at:
- For Tableau Server: Configure Tableau Connected Apps with OAuth 2.0 Trust(Link opens in a new window)
- For Tableau Cloud: Confgiure Tableau Connected Apps with OAuth 2.0 Trust(Link opens in a new window)
Note: Tableau Server admins can set up server-wide EAS through TSM. For more information, see Register EAS to Enable SSO for Embedded Content(Link opens in a new window).
Create Connected App
Create a connected app.
A connected app can be used to securely authenticate your users to Tableau content embedded in a custom application or for REST API authorization (introduced to Tableau Cloud in June 2022 and Tableau Server 2023). By creating a connected app, you can establish a trusted relationship between Tableau and any custom application.
For more information about connected apps, see one of the following:
- For Tableau Server: Configure Tableau Connected Apps to Enable SSO for Embedded Content
- For Tableau Cloud: Configure Tableau Connected Apps with Direct Trust(Link opens in a new window)
URI
POST api/api-version/sites/site-id/connected-apps/direct-trust
Note: The connected-applications
endpoint that performed this function was deprecated in API 3.17 (Tableau Cloud October 2022 / Tableau Server 2022.3), is no longer supported and may be retired in a future release.
Parameter Values
api-version | The version of the API to use, such as 3.24 . For more information, see REST API and Resource Versions. |
site-id | The unique ID of the site asset. |
Request Body
Tableau Cloud and Tableau Server using API 3.23 or later
<tsRequest>
<connectedApplication
name="name"
enabled="enabled"
domainSafelist="domainSafelist"
unrestrictedEmbedding="unrestrictedEmbedding">
<projectIds>
<projectId>project_id</projectId>
<projectId>project_id</projectId>
<projectId>project_id</projectId>
</projectIds>
<connectedApplication />
</tsRequest>
Tableau Server (or Tableau Cloud) using API 3.21 or earlier
<tsRequest>
<connectedApplication
name="name"
enabled="enabled"
projectId="project_id"
domainSafelist="domainSafelist"
unrestrictedEmbedding="unrestrictedEmbedding" />
</tsRequest>
Attribute Values
Any combination of attributes inside the <connectedApplication> element is valid, however name is required.
name | Name of the connected app. |
enabled | (Optional) Controls whether the connected app is enabled or not. Value can be "true" or "false". If the state is not specified, the connected app is set to "false" and not enabled by default. |
project_id |
(Optional, embedding workflows only) The IDs of the projects that the connected app's access level is scoped to. To get a project's project ID, see Query Projects. You can specify one project, multiple projects, all projects on a site.
Note: The stand-alone projectId attribute will be retired in a future release so we recommend using projectIds attribute instead. |
domainSafelist |
(Optional, embedding workflows only) A list of domains the connected app is allowed to be hosted. Specify one or more URLs, separated by spaces, using a format described in Domain allowlist rules(Link opens in a new window) in the Tableau Server Help or Domain allowlist rules(Link opens in a new window) in the Tableau Cloud Help. Important: We recommend using the domain allowlist as a security best practice to ensure Tableau content is only embedded in locations that you allow. For example: |
unrestrictedEmbedding | (Optional, embedding workflows only) Controls whether the connected app can be hosted on all domains. If "true" value is specified, the connected app can be hosted on all domains. If "false" value is specified, the connected app can only be hosted on the domains specified in the <domainSafelist> attribute. |
Permissions
Tableau Server admins or Tableau Cloud site admins only.
Response Code
201
Response Body
Example response:
<tsResponse>
<connectedApplication>
<name>ConnectedApp_MyCo</name>
<enabled>true</enabled>
<clientId>ac95d175-c844-4779-9d58-415e01fe7dab</clientId>
<projectIds>
<projectId>1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e</projectId>
<projectId>1234de4e-5d6d-7c8c-9b0b-1a2a3f4f5e0e</projectId>
</projectIds>
<createdAt>2021-08-10T18:46:30Z</createdAt>
<unrestrictedEmbedding>true</unrestrictedEmbedding>
</connectedApplication>
</tsResponse>
Note: When the scope of the connected app's access is set to all projects, the request does not return the projectId
attribute.
Version
Version 3.14 and later. For more information, see REST API and Resource Versions.
The resource, POST /api/api-version/sites/site-id/connected-apps/direct-trust, was added in version 3.17. The original resource, POST /api/api-version/sites/site-id/connected-applications, was deprecated in API 3.17 and will be retired in a future release.
Errors
HTTP status | error Code |
Condition | Details |
---|---|---|---|
400 | 400000 | Bad request | The content of the request body is missing or incomplete, or contains malformed XML. |
400 | 400109 | Bad request | The request body can't be empty. |
400 | 400143 | Generic connected app error | The connected app could not be deleted for some other reason than those specified in this table. |
403 | 403000 | Admin permissions required | A non-admin user called this method and doesn't have adequate permissions to perform the action. |
404 | 404000 | Resource not found | The site ID in the URI doesn't correspond to an existing site. |
404 | 404041 | Connected app not found | The requested connected app could not be found. |
Register EAS
Create a connected app with OAuth 2.0 trust by registering an external authorization server (EAS) to a site.
You can register an external authorization server (EAS) to establish a trust relationship between your Tableau Server site or Tableau Cloud site and EAS using the OAuth 2.0 standard protocol. By establishing a trust relationship, you’re able to provide your users with a single sign-on (SSO) experience to Tableau content embedded in your custom applications or REST API authorization through an identity provider (IdP) you've already configured.
Notes:
- Beginning in API version 3.22, you can register multiple EASs per site for Tableau Cloud.
- Beginning in API version 3.23, Tableau Server supports site-level EAS (and multiple registrations of EASs per site).
For more information, see one of the following:
- For Tableau Server: Register EAS to Enable SSO for Embedded Content(Link opens in a new window)
- For Tableau Cloud: Register EAS to Enable SSO for Embedded Content
URI
POST api/api-version/sites/site-id/connected-apps/external-authorization-servers
Parameter Values
api-version | The version of the API to use, such as 3.24 . For more information, see REST API and Resource Versions. |
site-id | The unique ID of the site asset. |
Request Body
<tsRequest>
<externalAuthorizationServer
issuerUrl="URL" jwksUri="URI" name="name"/>
</tsRequest>
Attribute Values
A combination of attributes inside the <externalAuthorizationServer> element is valid, however issuerUrl is required.
URL | The entity id of your identity provider (IdP) or URL that uniquely identifies your IdP. |
URI |
(Optional) The JSON Web Key (JKWS) of the EAS. |
name |
(Optional) The name of the connected app. If the name attribute is not specified, the connected app name defaults to "External Authorization Server." This attribute is available starting from API version 3.22 (February 2024). |
Permissions
Tableau Server admins or Tableau Cloud site admins only.
Response Code
201
Response Body
The request returns details about the EAS, including the following:
-
<name>
: The name of the connected app. -
<id>
: The ID of the EAS. -
<issuerUrl>:
The issuer URL of the EAS.
<jwksUri>:
The JSON web key set (JWKS) of the EAS.
You can use the returned EAS ID (<id>
) in Update EAS and Delete EAS requests.
Example response:
<tsResponse>
<externalAuthorizationServer>
<name>EAS_1</name>
<id>50bdc8cd-1aa4-48fe-a0e7-68982d85daa8</id>
<issuerUrl>https://dev-57741098.okta.com/oauth2/aus3gd9kw7ixSfBKC5d7</issuerUrl>
<jwksUri>https://dev-57741098.okta.com/jwks.json</jwksUri>
<createdAt>2022-04-07T03:50:34Z</createdAt>
</externalAuthorizationServer>
</tsResponse>
Version
Introduced in Tableau Cloud June 2022 (API 3.16). Introduced in Tableau Server 2024.1 (API 3.23).
Errors
HTTP status | error Code |
Condition | Details |
---|---|---|---|
400 | 400008 | Issuer URL missing | The required issuer URL is missing from the request body. |
400 | 400157 | Unexpected EAS error | There was a unexpected error when creating the connected app. |
400 | 400161 | EAS limit exceeded | The site has reached its limit of EAS that can be registered or the external authorization server (EAS) ID is not in the correct format. |
400 | 400194 | Issuer URL already configured | Another connected app on the site is using the same issuer URL. |
403 | 403000 | Admin permissions required | A non-admin user called this method and doesn't have adequate permissions to perform the action. |
404 | 404000 | Resource not found | The site ID in the URI doesn't correspond to an existing site. |
Create Connected App Secret
Generate a secret for a connected app.
Secrets are tokens shared by Tableau and a custom application, and used to establish a trusted relationship.
A maximum of two secrets can be associated with a connected app. These secrets do not expire and remain valid until deleted. If a connected app has already reached its two secret maximum when another one is generated, an error is thrown.
URI
POST api/api-version/sites/site-id/connected-apps/direct-trust/client-id/secrets
Note: The connected-applications
endpoint that performed this function was deprecated in API 3.17 (Tableau Cloud October 2022 / Tableau Server 2022.3), is no longer supported and may be retired in a future release.
Parameter Values
api-version | The version of the API to use, such as 3.24 . For more information, see REST API and Resource Versions. |
site-id | The unique ID of the site asset. |
client-id | The unique ID of the connected app. |
Request Body
None
Permissions
Tableau Server admins or Tableau Cloud site admins only.
Response Code
201
Response Body
The request returns details about the generated secret, including the secret value <value>
.
Example response:
<tsResponse>
<connectedApplicationSecret>
<value>TO7/wkW+45U001IBtyNbtyIMYQ/GBM0XlRXqsgYqPlY=</value>
<id>7ecc5c7c-d923-4ffd-917b-cab1bd89f03b</id>
<createdAt>2021-08-10T18:48:40Z</createdAt>
</connectedApplicationSecret>
</tsResponse>
Version
Version 3.14 and later. For more information, see REST API and Resource Versions.
The resource, POST /api/api-version/sites/site-id/connected-apps/direct-trust/client-id/secrets, was added in version 3.17. The original resource, POST /api/api-version/sites/site-id/connected-applications/client-id/secrets, was deprecated in version 3.17 and will be retired in a future release.
Errors
HTTP status | error Code |
Condition | Details |
---|---|---|---|
400 | 400143 | Generic connected app error | The connected app could not be deleted for some other reason than those specified in this table. |
400 | 400144 | Secret limit exceeded |
The connected app has already reached its two secret maximum. |
403 | 403000 | Admin permissions required | A non-admin user called this method and doesn't have adequate permissions to perform the action. |
404 | 404000 | Resource not found | The site ID in the URI doesn't correspond to an existing site. |
404 | 404041 | Connected app not found | The requested connected app could not be found. |
404 | 404042 | Secret not found | The requested secret for the connected app could not be found. |
Delete Connected App
Permanently remove a connected app.
Deleting the connected app also deletes the secrets associated with the connected app. For more information about deleting a connected app, see one of the following:
- For Tableau Server: Effects of deleting a connected app(Link opens in a new window)
- For Tableau Cloud: Effects of deleting a connected app(Link opens in a new window)
URI
DELETE api/api-version/sites/site-id/connected-apps/direct-trust/client-id
Note: The connected-applications
endpoint that performed this function was deprecated in API 3.17 (Tableau Cloud October 2022 / Tableau Server 2022.3), is no longer supported and may be retired in a future release.
Parameter Values
api-version | The version of the API to use, such as 3.24 . For more information, see REST API and Resource Versions. |
site-id | The unique ID of the site asset. |
client-id | The unique ID of the connected app. |
Permissions
Tableau Server admins or Tableau Cloud site admins only.
Response Code
204
Response Body
None
Version
Version 3.14 and later. For more information, see REST API and Resource Versions.
The resource, DELETE api/api-version/sites/site-id/connected-apps/direct-trust/client-id, was added in version 3.17. The original resource, DELETE api/api-version/sites/site-id/connected-applications/client-id, was deprecated in version 3.17 and will be retired in a future release.
Errors
HTTP status | error Code |
Condition | Details |
---|---|---|---|
400 | 400143 | Generic connected app error | The connected app could not be deleted for some other reason than those specified in this table. |
403 | 403000 | Admin permissions required | A non-admin user called this method and doesn't have adequate permissions to perform the action. |
404 | 404000 | Resource not found | The site ID in the URI doesn't correspond to an existing site. |
404 | 404041 | Connected app not found | The requested connected app could not be found. |
Delete EAS
Delete a registered external authorization server (EAS).
URI
DELETE api/api-version/sites/site-id/connected-apps/external-authorization-servers/eas-id
Parameter Values
api-version | The version of the API to use, such as 3.24 . For more information, see REST API and Resource Versions. |
site-id | The unique ID of the site asset. |
eas-id | The unique ID of the registered EAS. |
Permissions
Tableau Server admins or Tableau Cloud site admins only.
Response Code
204
Response Body
None
Version
Introduced in Tableau Cloud June 2022 (API 3.16). Introduced in Tableau Server 2024.2 (API 3.23).
Errors
HTTP status | error Code |
Condition | Details |
---|---|---|---|
400 | 400143 | Generic connected app error | The connected app could not be deleted for some other reason than those specified in this table. |
403 | 403000 | Admin permissions required | A non-admin user called this method and doesn't have adequate permissions to perform the action. |
404 | 404000 | Resource not found | The site ID in the URI doesn't correspond to an existing site. |
404 | 404047 | EAS not found | The requested EAS could not be found. |
Delete Connected App Secret
Permanently remove a secret associated with a connected app.
For more information about deleting a connected app, see one of the following:
- For Tableau Server: Effects of deleting a secret(Link opens in a new window)
- For Tableau Cloud: Effects of deleting a secret(Link opens in a new window)
URI
DELETE api/api-version/sites/site-id/connected-apps/direct-trust/client-id/secrets/secret-id
Note: The connected-applications
endpoint that performed this function was deprecated in API 3.17 (Tableau Cloud October 2022 / Tableau Server 2022.3), is no longer supported and may be retired in a future release.
Parameter Values
api-version | The version of the API to use, such as 3.24 . For more information, see REST API and Resource Versions. |
site-id | The unique ID of the site asset. |
client-id | The unique ID of the connected app. |
secret-id | The unique ID of the connected app secret. |
Permissions
Tableau Server admins or Tableau Cloud site admins only.
Response Code
204
Response Body
None
Version
Version 3.14 and later. For more information, see REST API and Resource Versions.
The resource, DELETE api/api-version/sites/site-id/connected-apps/direct-trust/client-id/secrets/secret-id, was added in version 3.17. The original resource, DELETE api/api-version/sites/site-id/connected-applications/client-id/secrets/secret-id, was deprecated in version 3.17 and will be retired in a future release.
Errors
HTTP status | error Code |
Condition | Details |
---|---|---|---|
400 | 400143 | Generic connected app error | The connected app could not be deleted for some other reason than those specified in this table. |
403 | 403000 | Admin permissions required | A non-admin user called this method and doesn't have adequate permissions to perform the action. |
404 | 404000 | Resource not found | The site ID in the URI doesn't correspond to an existing site. |
404 | 404041 | Connected app not found | The requested connected app could not be found. |
404 | 404042 | Secret not found | The requested secret for the connected app could not be found. |
Get Connected App
Query a connected app by its ID.
URI
GET api/api-version/sites/site-id/connected-apps/direct-trust/client-id
Note: The connected-applications
endpoint that performed this function was deprecated in API 3.17 (Tableau Cloud October 2022 / Tableau Server 2022.3), is no longer supported and may be retired in a future release.
Parameter Values
api-version | The version of the API to use, such as 3.24 . For more information, see REST API and Resource Versions. |
site-id | The unique ID of the site asset. |
client-id | The unique ID of the connected app. |
Request Body
None
Permissions
Tableau Server admins or Tableau Cloud site admins only.
Response Code
200
Response Body
The request returns details about the connected app, including the following:
<secret>
: Information related to the secret only if it has been previously generated. To create a secret for a connected app, see Create Connected App Secret. To get the secret value, see Query Connected App Secret.<name>
: Name of the connected app.<enabled>
: Whether the connected app is enabled or not.<clientId>
: The ID of the connected app.<projectId>:
The project that the connected app's access level is scoped to.<domainSafelist>:
If specified, one or more domains that the connected app is allowed to be hosted on.<unrestrictedEmbedding>
: Whether the connected app can be hosted on all domains. Iffalse
is returned, the<domainSafelist>
attribute determines the domain access.
Example response:
<tsResponse>
<connectedApplications>
<connectedApplication>
<secret>
<id>7ecc5c7c-d923-4ffd-917b-cab1bd89f03b</id>
<createdAt>2021-08-10T18:48:40Z</createdAt>
</secret>
<name>ConnectedApp_MyCo</name>
<enabled>true</enabled>
<clientId>ac95d175-c844-4779-9d58-415e01fe7dab</clientId>
<projectIds>
<projectId>1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e</projectId>
<projectId>1234de4e-5d6d-7c8c-9b0b-1a2a3f4f5e0e</projectId>
</projectIds>
<createdAt>2021-08-10T18:46:30Z</createdAt>
<unrestrictedEmbedding>false</unrestrictedEmbedding>
</connectedApplication>
<connectedApplications>
</tsResponse>
Version
Version 3.14 and later. For more information, see REST API and Resource Versions.
The resource, GET api/api-version/sites/site-id/connected-apps/direct-trust/client-id, was added in version 3.17. The original resource, GET api/api-version/sites/site-id/connected-applications/client-id, was deprecated in version 3.17 and will be retired in a future release.
Errors
HTTP status | error Code |
Condition | Details |
---|---|---|---|
400 | 400143 | Generic connected app error | The connected app could not be deleted for some other reason than those specified in this table. |
403 | 403000 | Admin permissions required | A non-admin user called this method and doesn't have adequate permissions to perform the action. |
404 | 404000 | Resource not found | The site ID in the URI doesn't correspond to an existing site. |
404 | 404041 | Connected app not found | The requested connected app could not be found. |
List Connected Apps
Query all connected apps configured on a site.
URI
GET api/api-version/sites/site-id/connected-apps/direct-trust
Note: The connected-applications
endpoint that performed this function was deprecated in API 3.17 (Tableau Cloud October 2022 / Tableau Server 2022.3), is no longer supported and may be retired in a future release.
Parameter Values
api-version | The version of the API to use, such as 3.24 . For more information, see REST API and Resource Versions. |
site-id | The unique ID of the site asset. |
Request Body
None
Permissions
Tableau Server admins or Tableau Cloud site admins only.
Response Code
200
Response Body
The request returns details about the connected app, including the following:
<secret>
: Information related to the secret only if it has been previously generated. To create a secret for a connected app, see Create Connected App Secret. To get the secret value, see Query Connected App Secret.<name>
: Name of the connected app.<enabled>
: Whether the connected app is enabled or not.<clientId>
: The ID of the connected app.<projectId>:
The project that the connected app's access level is scoped to.<domainSafelist>:
If specified, one or more domains that the connected app is allowed to be hosted on.<unrestrictedEmbedding>
: Whether the connected app can be hosted on all domains. Iffalse
is returned, the<domainSafelist>
attribute determines the domain access.
Example response:
<tsResponse>
<connectedApplications>
<connectedApplication>
<secret>
<id>7ecc5c7c-d923-4ffd-917b-cab1bd89f03b</id>
<createdAt>2021-08-10T18:48:40Z</createdAt>
</secret>
<name>ConnectedApp_MyCo</name>
<enabled>true</enabled>
<clientId>ac95d175-c844-4779-9d58-415e01fe7dab</clientId>
<projectIds>
<projectId>1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e</projectId>
<projectId>1234de4e-5d6d-7c8c-9b0b-1a2a3f4f5e0e</projectId>
</projectIds>
<createdAt>2021-08-10T18:46:30Z</createdAt>
<domainSafelist>https://myco.com</domainSafelist>
<unrestrictedEmbedding>false</unrestrictedEmbedding>
</connectedApplication>
<connectedApplication>
<name>ConnectedApp_MyCo_stage1</name>
<enabled>false</enabled>
<clientId>7370df14-2741-43f9-bbdd-450f707530a0</clientId>
<projectIds>
<projectId>11213e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e</projectId>
<projectId>21234de4e-5d6d-7c8c-9b0b-1a2a3f4f5e0e</projectId>
</projectIds>
<createdAt>2021-08-18T00:49:05Z</createdAt>
<unrestrictedEmbedding>true</unrestrictedEmbedding>
</connectedApplication>
<connectedApplication>
<name>ConnectedApp_MyCo_stage2</name>
<enabled>false</enabled>
<clientId>f1e57298-ecd4-46a9-b8d9-e5ab0bf76a82</clientId>
<createdAt>2021-08-18T00:54:30Z</createdAt>
</connectedApplication>
<connectedApplications>
</tsResponse>
Version
Version 3.14 and later. For more information, see REST API and Resource Versions.
The resource, GET api/api-version/sites/site-id/connected-apps/direct-trust, was added in version 3.17. The original resource, GET api/api-version/sites/site-id/connected-applications, was deprecated in version 3.17 and will be retired in a future release.
Errors
HTTP status | error Code |
Condition | Details |
---|---|---|---|
400 | 400143 | Generic connected app error | The connected app could not be deleted for some other reason than those specified in this table. |
403 | 403000 | Admin permissions required | A non-admin user called this method and doesn't have adequate permissions to perform the action. |
404 | 404000 | Resource not found | The site ID in the URI doesn't correspond to an existing site. |
404 | 404041 | Connected app not found | The requested connected app could not be found. |
List All Registered EAS
Get all external authorization servers (EASs) registered to a site.
URI
GET api/api-version/sites/site-id/connected-apps/external-authorization-servers
Parameter Values
api-version | The version of the API to use, such as 3.24 . For more information, see REST API and Resource Versions. |
site-id | The unique ID of the site asset. |
Request Body
None
Permissions
Tableau Server admins or Tableau Cloud site admins only.
Response Code
200
Response Body
The request returns details about the EAS, including the following:
-
<name>
: The name of the connected app. -
<id>
: The ID of the EAS. -
<issuerUrl>:
The issuer URL of the EAS.
Example response:
<tsResponse>
<externalAuthorizationServerList>
<externalAuthorizationServer>
<name>External Authorization Server</name>
<id>7ecc5c7c-d923-4ffd-917b-cab1bd89f03b</id>
<issuerUrl>https://dev-57741098.okta.com/oauth2/aus3gd9kw7ixSfBKC5d7</issuerUrl>
<createdAt>2022-04-07T03:50:34Z</createdAt>
</externalAuthorizationServer>
<externalAuthorizationServer>
<name>EAS_1</name>
<id>be5f8262-6ae4-407c-9765-dfe5b37cb4b5</id>
<issuerUrl>https://dev-57741099.okta.com/oauth2/aus3gd9kw7ixSfBKC5d7</issuerUrl>
<createdAt>2022-05-15T13:00:34Z</createdAt>
</externalAuthorizationServer>
<externalAuthorizationServerList>
</tsResponse>
Version
Introduced in Tableau Cloud June 2022 (API 3.16). Introduced in Tableau Server 2024.2 (API 3.23).
Errors
HTTP status | error Code |
Condition | Details |
---|---|---|---|
403 | 403000 | Admin permissions required | A non-admin user called this method and doesn't have adequate permissions to perform the action. |
404 | 404000 | Resource not found | The site ID in the URI doesn't correspond to an existing site. |
List Registered EAS
Get an external authorization server (EAS) registered to a site.
URI
GET api/api-version/sites/site-id/connected-apps/external-authorization-servers/eas-id
Parameter Values
api-version | The version of the API to use, such as 3.24 . For more information, see REST API and Resource Versions. |
site-id | The unique ID of the site asset. |
eas-id | The unique ID of the registered EAS. |
Request Body
None
Permissions
Tableau Server admins or Tableau Cloud site admins only.
Response Code
200
Response Body
The request returns details about the EAS, including the following:
-
<name>
: The name of the connected app. -
<id>
: The ID of the EAS. -
<issuerUrl>:
The issuer URL of the EAS.
Example response:
<tsResponse>
<externalAuthorizationServerList>
<externalAuthorizationServer>
<name>EAS_1</name>
<id>7ecc5c7c-d923-4ffd-917b-cab1bd89f03b</id>
<issuerUrl>https://dev-57741098.okta.com/oauth2/aus3gd9kw7ixSfBKC5d7</issuerUrl>
<createdAt>2022-04-07T03:50:34Z</createdAt>
</externalAuthorizationServer>
<externalAuthorizationServerList>
</tsResponse>
Version
Introduced in Tableau Cloud June 2022 (API 3.16). Introduced in Tableau Server 2024.2 (API 3.23).
Errors
HTTP status | error Code |
Condition | Details |
---|---|---|---|
400 | 400143 | Generic connected app error | The connected app could not be deleted for some other reason than those specified in this table. |
403 | 403000 | Admin permissions required | A non-admin user called this method and doesn't have adequate permissions to perform the action. |
404 | 404000 | Resource not found | The site ID in the URI doesn't correspond to an existing site. |
404 | 404047 | EAS not found | The requested EAS could not be found. |
Get Connected App Secret
Query a connected app secret and the token value using the connected app's ID.
Secrets are tokens shared by Tableau and a custom application, and used to establish a trusted relationship.
A maximum of two secrets can be associated with a connected app. These secrets do not expire and remain valid until deleted.
URI
GET api/api-version/sites/site-id/connected-apps/direct-trust/client-id/secrets/secret-id
Note: The connected-applications
endpoint that performed this function was deprecated in API 3.17 (Tableau Cloud October 2022 / Tableau Server 2022.3), is no longer supported and may be retired in a future release.
Parameter Values
api-version | The version of the API to use, such as 3.24 . For more information, see REST API and Resource Versions. |
site-id | The unique ID of the site asset. |
client-id | The unique ID of the connected app. |
secret-id | The unique ID of the connected app secret. |
Request Body
None
Permissions
Tableau Server admins or Tableau Cloud site admins only.
Response Code
200
Response Body
The request returns details about the secret associated with the connected app, including the following:
<value>
: The token value of the secret.<id>:
The ID of the secret.
Example response:
<tsResponse>
<connectedApplicationSecret>
<value>TO7/wkW+45U001IBtyNbtyIMYQ/GBM0XlRXqsgYqPlY=</value>
<id>7ecc5c7c-d923-4ffd-917b-cab1bd89f03b</id>
<createdAt>2021-08-10T18:48:40Z</createdAt>
</connectedApplicationSecret>
</tsResponse>
Version
Version 3.14 and later. For more information, see REST API and Resource Versions.
The resource, GET api/api-version/sites/site-id/connected-apps/direct-trust/client-id/secrets/secret-id, was added in version 3.17. The original resource, GET api/api-version/sites/site-id/connected-applications/client-id/secrets/secret-id, was deprecated in version 3.17 and will be retired in a future release.
Errors
HTTP status | error Code |
Condition | Details |
---|---|---|---|
400 | 400143 | Generic connected app error | The connected app could not be deleted for some other reason than those specified in this table. |
403 | 403000 | Admin permissions required | A non-admin user called this method and doesn't have adequate permissions to perform the action. |
404 | 404000 | Resource not found | The site ID in the URI doesn't correspond to an existing site. |
404 | 404041 | Connected app not found | The requested connected app could not be found. |
404 | 404042 | Secret not found | The requested secret for the connected app could not be found. |
Update Connected App
Update a connected app.
URI
PUT api/api-version/sites/site-id/connected-apps/direct-trust/client-id
Note: The connected-applications
endpoint that performed this function was deprecated in API 3.17 (Tableau Cloud October 2022 / Tableau Server 2022.3), is no longer supported and may be retired in a future release.
Parameter Values
api-version | The version of the API to use, such as 3.24 . For more information, see REST API and Resource Versions. |
site-id | The unique ID of the site asset. |
client-id | The unique ID of the connected app. |
Request Body
For Tableau Cloud and Tableau Server using API 3.23 or later
<tsRequest>
<connectedApplication
name="name"
enabled="enabled"
domainSafelist="domainSafelist"
unrestrictedEmbedding="unrestrictedEmbedding">
<projectIds>
<projectId>project_id</projectId>
<projectId>project_id</projectId>
<projectId>project_id</projectId>
</projectIds>
<connectedApplication />
</tsRequest>
For Tableau Server (or Tableau Cloud) using API 3.21 or earlier
<tsRequest>
<connectedApplication
name="name"
enabled="enabled"
projectId="project_id" domainSafelist="domainSafelist"
unrestrictedEmbedding="unrestricedEmbedding" />
</tsRequest>
Attribute Values
Any combination of attributes inside the <connectedApplication> element is valid.
name | (Optional) The new name of the connected app. |
enabled | (Optional) Controls whether the connected app is enabled or not. Value can be "true" or "false". If the state is not specified, the connected app is set to "false" and not enabled by default. |
project_id |
(Optional, embedding workflows only) The ID of the project that the connected app's access level is scoped to. To get the project ID, see Query Projects. You can specify one project, multiple projects, and all projects on a site.
Note: The stand-alone projectId attribute will be retired in a future release so we recommend using projectIds attribute instead. |
domainsafelist |
(Optional, embedding workflows only ) A list of domains the connected app is allowed to be hosted. Specify one or more URLs, separated by spaces, using a format described in Domain allowlist rules(Link opens in a new window) in the Tableau Server Help or Domain allowlist rules(Link opens in a new window) in the Tableau Cloud Help. Important: We recommend using the domain allowlist as a security best practice to ensure Tableau content is only embedded in locations that you allow. For example: |
unrestrictedEmbedding | (Optional, embedding workflows only) Controls whether the connected app can be hosted on all domains. If "true" value is specified, the connected app can trust and connect to all domains. If "false" value is specified, the connected app can only be hosted on the domains specified in the <domainSafelist> attribute. |
Permissions
Tableau Server admins or Tableau Cloud site admins only.
Response Code
200
Response Body
Example response:
<tsResponse>
<connectedApplication>
<secret>
<id>d8a51b6c-bf70-4aaf-959b-93d2ba4897e6</id>
<createdAt>2021-08-18T17:59:11Z</createdAt>
</secret>
<name>ConnectedApp_MyCo</name>
<enabled>true</enabled>
<clientId>9486dee1-ca98-4144-b6e0-f5c555e64796</clientId>
<projectIds>
<projectId>1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e</projectId>
<projectId>1234de4e-5d6d-7c8c-9b0b-1a2a3f4f5e0e</projectId>
</projectIds>
<createdAt>2021-08-18T17:48:03Z</createdAt>
<unrestrictedEmbedding>true</unrestrictedEmbedding>
</connectedApplication>
</tsResponse>
Notes:
- The request will return the secret associated with the connected app only if it has been previously generated. To get the secret value, see Query Connected App Secret.
- When the scope of the connected app's access is set to all projects, the request does not return the
projectId
attribute.
Version
Version 3.14 and later. For more information, see REST API and Resource Versions.
The resource, PUT api/api-version/sites/site-id/connected-apps/direct-trust/client-id, was added in version 3.17. The original resource, PUT api/api-version/sites/site-id/connected-applications/client-id, was deprecated in API 3.17 and will be retired in a future release.
Errors
HTTP status | error Code |
Condition | Details |
---|---|---|---|
400 | 400000 | Bad request | The content of the request body is missing or incomplete, or contains malformed XML. |
400 | 400109 | Bad request | The request body can't be empty. |
400 | 400143 | Generic connected app error | The connected app could not be deleted for some other reason than those specified in this table. |
403 | 403000 | Admin permissions required | A non-admin user called this method and doesn't have adequate permissions to perform the action. |
404 | 404000 | Resource not found | The site ID in the URI doesn't correspond to an existing site. |
404 | 404041 | Connected app not found | The requested connected app could not be found. |
Update EAS
Update a connected app with OAuth 2.0 trust.
Notes:
- Beginning in API version 3.22, you can register multiple EASs per site for Tableau Cloud.
- Beginning in API version 3.23, Tableau Server supports site-level EAS (and multiple registrations of EASs per site).
URI
PUT api/api-version/sites/site-id/connected-apps/external-authorization-servers/eas-id
Parameter Values
api-version | The version of the API to use, such as 3.24 . For more information, see REST API and Resource Versions. |
site-id | The unique ID of the site asset. |
eas-id | The unique ID of the registered EAS. |
Request Body
<tsRequest>
<externalAuthorizationServer
issuerUrl="URL"
jwksUri="URI"
name="name" />
</tsRequest>
Attribute Values
A combination of attributes inside the <externalAuthorizationServer> element is valid.
URL | (Optional) The entity id of your identity provider (IdP) or URL that uniquely identifies your IdP. |
URI |
(Optional) The JSON Web Key (JKWS) of the EAS. |
name |
(Optional) The name of the connected app. If the name attribute is not specified, the connected app name defaults to "External Authorization Server." This attribute is available starting from API version 3.22 (February 2024). |
Permissions
Tableau Server admins or Tableau Cloud site admins only.
Response Code
200
Response Body
The request returns details about the EAS, including the following:
-
<name>
: The name of the connected app. -
<id>
: The ID of the EAS. -
<issuerUrl>:
The issuer URL of the EAS.
<jwksUri>:
The JSON web key set (JWKS) of the EAS.
Example response:
<tsResponse>
<externalAuthorizationServer>
<name>EAS_2</name>
<id>50bdc8cd-1aa4-48fe-a0e7-68982d85daa8</id>
<issuerUrl>https://dev-57741098.okta.com/oauth2/aus3gd9kw7ixSfBKC5d7</issuerUrl>
<jwksUri>https://dev-57741098.okta.com/jwks.json</jwksUri>
<createdAt>2022-04-07T03:50:34Z</createdAt>
</externalAuthorizationServer>
</tsResponse>
Version
Introduced in Tableau Cloud June 2022 (API 3.16). Introduced in Tableau Server 2024.2 (API 3.23).
Errors
HTTP status | error Code |
Condition | Details |
---|---|---|---|
400 | 400008 | Issuer URL missing | The request body contains an empty issuer URL attribute. |
400 | 400157 | Unexpected EAS error | There was an unexpected error when updating the connected app. |
400 | 400194 | Issuer URL already configured | Another connected app on the site is using the same issuer URL. |
403 | 403000 | Admin permissions required | A non-admin user called this method and doesn't have adequate permissions to perform the action. |
404 | 404000 | Resource not found | The site ID in the URI doesn't correspond to an existing site. |
404 | 404047 | EAS not found | The requested EAS could not be found. |