Skip to content

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.

Environment

  • A Rancher v2.x instance

  • A cluster-scoped Rancher API token

Situation

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:

{
  "type":"error",
  "status":"401",
  "message":"clusterID does not match"
}

Resolution

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.

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 or 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.

Additional Information

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

Disclaimer

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.