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

This document (000020196) is provided subject to the disclaimer at the end of this document.



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.


This Support Knowledgebase provides a valuable tool for SUSE customers and parties interested in our products and solutions to acquire information, ideas and learn from one another. Materials are provided for informational, personal or non-commercial use within your organization and are presented "AS IS" WITHOUT WARRANTY OF ANY KIND.

  • Document ID:000020196
  • Creation Date: 06-May-2021
  • Modified Date:06-May-2021
    • SUSE Rancher

< Back to Support Search

For questions or concerns with the SUSE Knowledgebase please contact: tidfeedback[at]

SUSE Support Forums

Get your questions answered by experienced Sys Ops or interact with other SUSE community experts.

Join Our Community

Support Resources

Learn how to get the most from the technical support you receive with your SUSE Subscription, Premium Support, Academic Program, or Partner Program.

SUSE Customer Support Quick Reference Guide SUSE Technical Support Handbook Update Advisories
Support FAQ

Open an Incident

Open an incident with SUSE Technical Support, manage your subscriptions, download patches, or manage user access.

Go to Customer Center