Tableau User Management API Guide

Auth method: Personal Access Token (PAT) or username/password credentials exchanged for a session token via /auth/signin. Token passed as X-Tableau-Auth header on subsequent requests.

Setup steps

1. In Tableau Cloud or Tableau Server, navigate to My Account Settings and generate a Personal Access Token (PAT) with a name and note the secret.
2. POST to /api//auth/signin with credentials body (PAT name + secret, or username + password) and the target site contentUrl.
3. Extract the token value from the response credentials.token field.
4. Include the token as the X-Tableau-Auth header on all subsequent API requests.
5. Tokens expire after inactivity (default 240 minutes); re-authenticate or use PATs which support longer-lived sessions.

Required scopes

Sign In (get auth token)

• Method: POST
• URL: https://<server>/api/<version>/auth/signin
• Watch out for: PAT secrets are shown only once at creation. Session tokens expire after inactivity (default 240 min on Cloud).

Request example

POST /api/3.22/auth/signin
{
  "credentials": {
    "personalAccessTokenName": "my-token",
    "personalAccessTokenSecret": "<secret>",
    "site": { "contentUrl": "mysite" }
  }
}

Response example

{
  "credentials": {
    "token": "<session-token>",
    "site": { "id": "<site-id>", "contentUrl": "mysite" },
    "user": { "id": "<user-id>" }
  }
}

Add User to Site

• Method: POST
• URL: https://<server>/api/<version>/sites/<site-id>/users
• Watch out for: On Tableau Cloud, name must be the user's email address. Adding a user does not send an invitation automatically unless configured.

Request example

POST /api/3.22/sites/<site-id>/users
X-Tableau-Auth: <token>
{
  "user": {
    "name": "user@example.com",
    "siteRole": "Viewer",
    "authSetting": "SAML"
  }
}

Response example

{
  "user": {
    "id": "<user-id>",
    "name": "user@example.com",
    "siteRole": "Viewer",
    "authSetting": "SAML"
  }
}

Get Users on Site

• Method: GET
• URL: https://<server>/api/<version>/sites/<site-id>/users
• Watch out for: Default pageSize is 100; max is 1000. Must iterate pageNumber to retrieve all users when totalAvailable > pageSize.

Request example

GET /api/3.22/sites/<site-id>/users?pageSize=100&pageNumber=1
X-Tableau-Auth: <token>

Response example

{
  "pagination": { "pageNumber": 1, "pageSize": 100, "totalAvailable": 250 },
  "users": {
    "user": [
      { "id": "<id>", "name": "user@example.com", "siteRole": "Viewer" }
    ]
  }
}

Get User by ID

• Method: GET
• URL: https://<server>/api/<version>/sites/<site-id>/users/<user-id>
• Watch out for: Returns site-scoped user data only; does not return server-level attributes.

Request example

GET /api/3.22/sites/<site-id>/users/<user-id>
X-Tableau-Auth: <token>

Response example

{
  "user": {
    "id": "<user-id>",
    "name": "user@example.com",
    "siteRole": "Explorer",
    "lastLogin": "2024-11-01T10:00:00Z"
  }
}

Update User

• Method: PUT
• URL: https://<server>/api/<version>/sites/<site-id>/users/<user-id>
• Watch out for: Downgrading a Creator who owns published content may fail or require content reassignment first.

Request example

PUT /api/3.22/sites/<site-id>/users/<user-id>
X-Tableau-Auth: <token>
{
  "user": {
    "siteRole": "Creator",
    "authSetting": "SAML"
  }
}

Response example

{
  "user": {
    "id": "<user-id>",
    "name": "user@example.com",
    "siteRole": "Creator"
  }
}

Remove User from Site

• Method: DELETE
• URL: https://<server>/api/<version>/sites/<site-id>/users/<user-id>
• Watch out for: If the user owns content (workbooks, data sources), the request will fail with a 409 error unless content is reassigned or deleted first.

Request example

DELETE /api/3.22/sites/<site-id>/users/<user-id>
X-Tableau-Auth: <token>

Response example

HTTP 204 No Content

Add User to Group

• Method: POST
• URL: https://<server>/api/<version>/sites/<site-id>/groups/<group-id>/users
• Watch out for: User must already exist on the site before being added to a group.

Request example

POST /api/3.22/sites/<site-id>/groups/<group-id>/users
X-Tableau-Auth: <token>
{
  "user": { "id": "<user-id>" }
}

Response example

{
  "user": {
    "id": "<user-id>",
    "name": "user@example.com",
    "siteRole": "Viewer"
  }
}

Query Groups on Site

• Method: GET
• URL: https://<server>/api/<version>/sites/<site-id>/groups
• Watch out for: Active Directory / LDAP-imported groups show a domain attribute; local groups do not.

Request example

GET /api/3.22/sites/<site-id>/groups?pageSize=100&pageNumber=1
X-Tableau-Auth: <token>

Response example

{
  "pagination": { "pageNumber": 1, "pageSize": 100, "totalAvailable": 12 },
  "groups": {
    "group": [
      { "id": "<group-id>", "name": "Sales Team" }
    ]
  }
}

• Rate limits: Tableau does not publish explicit numeric rate limits in its official REST API documentation. Tableau Cloud enforces undisclosed throttling; Tableau Server limits depend on server configuration.

• Rate-limit headers: No

• Retry-After header: No

• Rate-limit notes: No official rate-limit headers or Retry-After behavior documented. Tableau recommends avoiding tight polling loops and batching requests where possible.

• Pagination method: offset

• Default page size: 100

• Max page size: 1000

• Pagination pointer: pageNumber (1-based) and pageSize query parameters; response includes pagination.totalAvailable, pagination.pageNumber, pagination.pageSize

• Webhooks available: Yes

• Webhook notes: Tableau REST API supports webhooks (Tableau Cloud and Tableau Server 2019.4+) for event-driven notifications. Webhooks fire HTTP POST payloads to a configured URL.

• Alternative event strategy: No native user-lifecycle webhook events (e.g., user-added, user-removed) are documented. Poll the REST API or use SCIM provisioning events via the IdP for user lifecycle changes.

• Webhook events: workbook-created, workbook-updated, workbook-deleted, datasource-created, datasource-updated, datasource-deleted, view-deleted

• SCIM available: Yes

• SCIM version: 2.0

• Plan required: Tableau Cloud (all tiers – Creator, Explorer, Viewer); SAML SSO must be configured as a prerequisite.

• Endpoint: https://prod-useast-a.online.tableau.com/scim/v2/ (base URL varies by Tableau Cloud pod; obtained from Admin > Authentication > SCIM settings in the UI)

• Supported operations: GET /Users – list users, POST /Users – provision user, GET /Users/ – get user, PUT /Users/ – replace user, PATCH /Users/ – update user attributes or deactivate, DELETE /Users/ – remove user, GET /Groups – list groups, POST /Groups – create group, GET /Groups/ – get group, PATCH /Groups/ – update group membership, DELETE /Groups/ – delete group

Limitations:

• SAML SSO must be fully configured before enabling SCIM.
• SCIM secret token is generated once in the Tableau Cloud Admin UI; if lost, a new token must be regenerated (invalidating the old one).
• Supported IdPs with documented integration guides: Okta, Microsoft Entra ID (Azure AD), OneLogin.
• Google Workspace is not listed as a supported SCIM IdP in official docs.
• SCIM provisioning maps to Tableau site roles; role assignment via SCIM depends on IdP group-to-role mapping configuration.
• Deactivating a user via SCIM (active=false) removes them from the site but does not delete their content.
• SCIM endpoint base URL is pod-specific and must be copied from the Tableau Cloud Admin UI.

Three integration patterns cover the majority of identity graph use cases against Tableau Cloud.

For provisioning a net-new user: authenticate via POST /auth/signin to obtain a session token and site UUID (the internal UUID from the signin response, not the contentUrl string), then POST /sites/<site-id>/users with name (must be an email address on Tableau Cloud), siteRole, and authSetting.

Capture the returned user.id, resolve the target group via GET /sites/<site-id>/groups, and add the user with POST /sites/<site-id>/groups/<group-id>/users.

If authSetting is SAML, no password is set via the API - the user authenticates through the IdP on first access.

For deprovisioning: resolve user-id via GET /sites/<site-id>/users with a name filter, then attempt DELETE /sites/<site-id>/users/<user-id>.

A 409 Conflict response means the user owns content;

content must be reassigned via the reassign-content endpoint or deleted before the DELETE will succeed.

Setting siteRole to Unlicensed via PUT is a valid soft-deactivation that revokes access while preserving content and avoiding the 409 path entirely.

For bulk sync via SCIM with Okta or Entra ID: enable SAML first, then enable SCIM in the Tableau Cloud Admin UI and copy the pod-specific base URL and generated token.

Configure the SCIM connector in the IdP with those credentials, map userName to the user's email, and drive role assignment through IdP group-to-role rules.

Validate with a single user before enabling full group push.

Note that regenerating the SCIM token in Tableau immediately breaks the IdP sync until the new token is propagated.

Provision a new user and assign to a group

1. POST /auth/signin with PAT credentials to obtain a session token and site-id.
2. POST /sites//users with name (email), siteRole, and authSetting=SAML to create the user.
3. Capture the returned user.id from the response.
4. GET /sites//groups to find the target group-id by name.
5. POST /sites//groups//users with the user.id to add the user to the group.
6. POST /auth/signout to invalidate the session token.

Watch out for: If authSetting is SAML, the user must log in via the IdP on first access; no password is set via the API.

Deprovision a user (remove from site)

1. POST /auth/signin to obtain session token.
2. GET /sites//users?filter=name:eq: to resolve the user-id.
3. Attempt DELETE /sites//users/.
4. If HTTP 409 is returned, call POST /sites//users//content/reassign (or delete content) to clear ownership.
5. Retry DELETE /sites//users/.
6. Alternatively, set siteRole to Unlicensed via PUT to revoke access without deleting the user.

Watch out for: Content ownership must be resolved before deletion. Using Unlicensed role is a safer soft-deactivation that preserves content.

Bulk user sync via SCIM with Okta

1. In Tableau Cloud Admin > Authentication, enable SAML and then enable SCIM; copy the SCIM base URL and generate the secret token.
2. In Okta, add the Tableau Cloud app from the Okta Integration Network.
3. Configure the SCIM connector in Okta with the Tableau SCIM base URL and bearer token.
4. Map Okta profile attributes to Tableau SCIM attributes (userName → email, siteRole via group rules).
5. Assign Okta groups to the Tableau app; Okta will POST /Users and POST /Groups to provision members.
6. Test with a single user assignment before enabling full group push.

Watch out for: SAML must be fully configured and tested before SCIM is enabled. Regenerating the SCIM token in Tableau immediately invalidates the previous token, breaking the Okta sync until updated.

The most common integration failure is treating the contentUrl site identifier as the site UUID. The REST API requires the internal UUID in URL paths; this value is returned in the auth/signin response and is not the human-readable site name visible in the Admin UI.

Passing the wrong identifier returns a 404 with no descriptive error.

A second trap is the 409 Conflict on user deletion. Callers that do not handle this response code will silently fail to deprovision users who own content, leaving licensed seats occupied and access intact.

Any identity graph integration must implement a content-ownership check and resolution step - either automated reassignment or a fallback to Unlicensed role - before treating a deprovision operation as complete.

Finally, API version pinning is required. Tableau increments the API version with each product release, and using an outdated version in the URL path may silently omit newer fields or endpoints. There is no automatic redirect to the latest version;

callers must explicitly track and update the version segment against Tableau's published compatibility matrix.