HTTP 401 "clusterID does not match" error using cluster-scoped Rancher API token in Rancher v2.x

Table of Contents


When attempting to perform operations against the Rancher v2.x API, with a cluster-scoped API token, you receive a HTTP 401 response code with a body of the following format:

  "message":"clusterID does not match"


  • A Rancher v2.x instance
  • A cluster-scoped Rancher API token

Root cause

The primary purpose of cluster-scoped API tokens is to permit access to the Kubernetes API for a specific cluster via Rancher, i.e. via the endpoint https://<rancher_url>/k8s/clusters/<cluster_id> for the matching cluster. Cluster-scoped tokens can be used to interact directly with the Kubernetes API of clusters configured with an Authorized Cluster Endpoint.

In addition, a cluster-scoped token also works for resources under the Rancher v3 API endpoint for that cluster, at https://<rancher_url>/v3/clusters/<cluster_id>.

The token is not valid for the other available API endpoints, nor for other clusters. Attempts to perform API operations on other clusters or endpoints with a cluster-scoped token will result in the HTTP 401 "clusterID does not match" error.


Only use a cluster-scoped API token where you wish to restrict usage of the token to the Kubernetes API for that cluster, or the Rancher v3 cluster endpoint. To permit access to other API endpoints, or to use a token for API access to multiple clusters, create a Rancher API token that is not cluster-scoped.

Further reading

You can read more on the Rancher v2.x API within the API documentation.

Was this article helpful?
0 out of 0 found this helpful



Please sign in to leave a comment.