Tableau Credentials API¶

Change the Tableau Server login that MetaMiner uses for an environment from a script, without restarting the MetaMiner Server (MMS), and see which login each node uses.

What you can change¶

Login	By this API	Fields
Tableau Server REST sign-in (user name and password)	Yes, live	`user`, `password`
TSM login	Yes, live	`tsmUser`, `tsmPassword`
Tableau repository login	Yes; takes effect at the next MMS restart	`repoUser`, `repoPassword`
Tableau Cloud personal access token	No	Rotate Tableau Cloud tokens in the MetaMiner Administrator (MMA)

The API works on Tableau Server environments only. A call for a Tableau Cloud environment answers 400 with "Tableau Cloud environment () signs in with a personal access token; this API changes the username and password of a Tableau Server environment" and changes nothing.

The API does not change any password in Tableau. Change it in Tableau Server or your directory first, then tell MetaMiner.

Before you begin¶

The environment is configured on the MMS you call. It does not need to be running.
You have the token of an admin API client without site limits. A client limited to environments may change only those environments. See Manage API Clients.
You know the environment id (envId) and its exact display name (envName). GET /tab/credentials/status lists both for every Tableau Server environment.
The MMS configuration is not encrypted. With an encrypted configuration the API answers 501 "ENCRYPTED CONFIG NOT CURRENTLY SUPPORTED FOR CREDENTIAL SWAP".
Your script calls https://<mms-host>:<port>. The request body carries a password in clear text, so use HTTPS (see HTTPS and Network Exposure).

Change credentials¶

POST /tab/credentials - an admin API client without site limits, for an environment it may use.

Field	Type	Required	Meaning
`envId`	number	Yes	The environment id
`envName`	text	Yes	The environment's display name, exactly as configured (case-sensitive). A guard against changing the wrong environment.
`password`	text	One of the three passwords	New Tableau Server REST password
`user`	text	No	New REST user name. Omit to keep the current one.
`tsmUser`, `tsmPassword`	text	No	New TSM login
`repoUser`, `repoPassword`	text	No	New repository login
`cluster`	boolean	No	`false` = change this node only. Default: every node of a high-availability pair.
`waitSeconds`	number	No	How long to wait for the other nodes: default 30, 0 to 120

What happens:

The token is checked before the body is read or Tableau is contacted.
MMS finds the environment by envId and checks envName against it.
MMS validates each login you sent: a Tableau REST sign-in, a TSM sign-in, a repository connection.
If any login is rejected, nothing is applied or saved, and the answer says why.
If all are accepted, MMS applies them to the running connection, saves them, and sends the change to the other nodes (see High-availability propagation).

A body that is not a JSON object is rejected and nothing changes.

Response¶

200 OK

{
  "status": "ok",
  "message": "Credentials updated for env <envName>",
  "applied": ["REST"],
  "cluster": "SYNCED",
  "nodes": [ { "nodeId": "<node>", "host": "<host>", "status": "APPLIED" } ]
}

Field	Meaning
`status`, `message`	`ok` and a short text
`applied`	The logins changed: `REST`, `TSM`, `REPO`
`notes`	Extra information, for example that a repository login takes effect at the next MMS restart
`cluster`, `clusterMessage`	The result on the other nodes (see below)
`rotationId`	Identifies this change on every node
`nodes`	One entry per node: `nodeId`, `host`, `status`, `message`

Status	Meaning
`200`	Validated, applied and saved on this node; `cluster` reports the other nodes
`400`	`Missing required parameter: envId`, `envName` or `password`; `Tableau REST API validation failed ...` (a login was rejected, nothing changed); a Tableau Cloud environment; a repository login for an environment without a repository connection
`401`	No token, or not the token of an active API client
`403`	The client is not an admin client, has site limits, or may not use this environment
`404`	`No Tableau environment with id <id> is configured on this node`, or `envName '<x>' does not match environment <id> ...`
`413`	Body over 64 KiB
`500`	`status` `applied_not_persisted`: active now, but the save failed; it will not survive an MMS restart unless a later save succeeds
`500`	`status` `persistence_unconfirmed`: active now, but the save was not confirmed within 10 seconds
`500`	Unexpected error (plain text body)
`501`	The MMS configuration is encrypted
`503`	`API_CLIENTS_UNAVAILABLE`: the API clients cannot be checked; retry

The bodies of 400 to 404 and 501 are {"status": "error", "message": "..."}. See Status Codes and Errors.

curlPowerShell

curl -sS -X POST "https://<mms-host>:<port>/tab/credentials" --max-time 180 \
  -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
  -d '{"envId": <envId>, "envName": "<display name>", "user": "<user>", "password": "<new password>"}'

$body = @{ envId = <envId>; envName = "<display name>"; user = "<user>"; password = "<new password>" } | ConvertTo-Json
Invoke-RestMethod -Method Post -Uri "https://<mms-host>:<port>/tab/credentials" -TimeoutSec 180 `
  -Headers @{ Authorization = "Bearer <token>" } -ContentType "application/json" -Body $body

The call waits for a live Tableau sign-in and, in a high-availability pair, for the other nodes (waitSeconds). Set the client timeout above both; 180 seconds covers the maximum wait.

If MMA was open on the server during the change, a later save from that MMA keeps the newer credentials.

Read credential status¶

GET /tab/credentials/status - an admin API client without site limits.

Returns, per Tableau Server environment, who MetaMiner signs in as and when each login last changed, on this node and on every node of the pair, plus recent changes and their result per node. It never returns a password.

Field	Meaning
`envs`	This node: `envId`, `envName`, `host`, `username`, `credentialsUpdatedAt`, and `tsmUsername` / `repoUsername` with their change times where configured
`cluster.sync`	`ON` or `OFF`
`cluster.nodes`	Each node: `nodeId`, `host`, `lastSeen`, and its `envs`
`cluster.recentChanges`	Recent changes and their result per node

Status	Meaning
`200`	Status returned
`401` / `503`	See Status Codes and Errors
`403`	Not an admin client without site limits
`404`	Any other `GET` path under `/tab/credentials`

curlPowerShell

curl -sS "https://<mms-host>:<port>/tab/credentials/status" -H "Authorization: Bearer <token>"

(Invoke-RestMethod -Uri "https://<mms-host>:<port>/tab/credentials/status" `
  -Headers @{ Authorization = "Bearer <token>" }).envs | Format-Table envId, envName, username

Re-send to the other nodes¶

POST /tab/credentials/sync - same access rule as the change.

Body: {"envId": <envId>, "envName": "<display name>"}. This node checks its current login against Tableau and sends it to the other nodes again. Use it when a node shows EXPIRED or NOT_SENT. The answer has the same shape as a change.

High-availability propagation¶

In a high-availability pair you call one node, through the load balancer or directly; either node takes the call. That node validates, applies and saves the change, then records it in the shared Flow Scheduler database. Each other node picks it up within seconds, validates it with Tableau itself and applies it, unless it already has the same or a newer change. Nodes never call each other.

`cluster`	Meaning
`SYNCED`	Every other node has the change
`PENDING`	At least one node has not applied it yet; it does when its Flow Scheduler next checks, or when it is back if it is down
`PARTIAL`	At least one node did not take the change; see its `status` and `message`
`SINGLE_NODE`	No other node is registered
`UNAVAILABLE`	The local Flow Scheduler did not answer, so only this node changed; call the API on each node. On a single server with the Flow Scheduler switched off, this is the normal answer and the change on this server is complete.
`OFF`	`cluster: false` was sent, or cluster sync is switched off on this server: only this node changed

Node `status`	Meaning
`APPLIED`	Applied on that node (always so for the node you called)
`PENDING`	Not applied yet
`STALE`	That node already had the same or a newer change
`EXPIRED`	Not picked up in time (24 hours by default, see Configuration Reference); call `/tab/credentials/sync`
`NOT_SENT`	This node could not send it; `message` says why
`KEY_CHANGED`	Not sent: that node must be trusted again first. `message` names the step; if it is unclear, contact Infolytik support before retrying
`REFUSED`, `SUPERSEDED`	Not applied on that node; `message` says why

Verify¶

The call returns 200 with "status": "ok", and in a pair cluster is SYNCED.
GET /tab/credentials/status shows the new username and a new credentialsUpdatedAt on every node.
The next pull of the environment signs in without errors.