API Tokens

By default, some cluster-level API tokens are generated with infinite time-to-live (ttl=0). In other words, API tokens with ttl=0 never expire unless you invalidate them. Tokens are not invalidated by changing a password.

You can deactivate API tokens by deleting them or by deactivating the user account.

Deleting Tokens

To delete a token:

1. Go to the list of all tokens in the Rancher API view at https://<Rancher-Server-IP>/v3/tokens.

2. Access the token you want to delete by its ID. For example, https://<Rancher-Server-IP>/v3/tokens/kubectl-shell-user-vqkqt

3. Click Delete.

The following is a complete list of tokens generated with ttl=0:

Token	Description
kubeconfig-*	Kubeconfig token
kubectl-shell-*	Access to kubectl shell in the browser
agent-*	Token for agent deployment
compose-token-*	Token for compose
helm-token-*	Token for Helm chart deployment
*-pipeline*	Pipeline token for project
telemetry-*	Telemetry token
drain-node-*	Token for drain (Rancher uses kubectl for drain because there is no native Kubernetes API)

Setting TTL on Kubeconfig Tokens

Admins can set a global time-to-live (TTL) on Kubeconfig tokens. Changing the default kubeconfig TTL can be done by navigating to global settings and setting kubeconfig-default-token-ttl-minutes to the desired duration in minutes. The default value of kubeconfig-default-token-ttl-minutes is 0, which means that tokens never expire.

note

This setting is used by all kubeconfig tokens except those created by the CLI to generate kubeconfig tokens.

Disable Tokens in Generated Kubeconfigs

1. Set the kubeconfig-generate-token setting to false. This setting instructs Rancher to no longer automatically generate a token when a user clicks on download a kubeconfig file. When this setting is deactivated, a generated kubeconfig references the Rancher CLI to retrieve a short-lived token for the cluster. When this kubeconfig is used in a client, such as kubectl, the Rancher CLI needs to be installed to complete the log in request.

2. Set the kubeconfig-token-ttl-minutes setting to the desired duration in minutes. By default, kubeconfig-token-ttl-minutes is 960 (16 hours).

Token Hashing

Users can enable token hashing, where tokens undergo a one-way hash using the SHA256 algorithm. This is a non-reversible process: once enabled, this feature cannot be disabled. It is advisable to take backups prior to enabling and/or evaluating in a test environment first.

To enable token hashing, refer to this section.

This feature affects all tokens which include, but are not limited to, the following:

• Kubeconfig tokens
• Bearer tokens API keys/calls
• Tokens used by internal operations

Token Settings

These global settings affect Rancher token behavior.

Setting	Description
auth-user-session-ttl-minutes	TTL in minutes on a user auth session token.
kubeconfig-default-token-ttl-minutes	Default TTL applied to all kubeconfig tokens except those generated by Rancher CLI. Introduced in version 2.6.6.
kubeconfig-token-ttl-minutes	TTL used for tokens generated via the CLI. Deprecated since version 2.6.6, and removed in 2.8.0. Rancher v2.8 and later instead use kubeconfig-default-token-ttl-minutes for all kubeconfig tokens.
auth-token-max-ttl-minutes	Max TTL for all tokens except those controlled by auth-user-session-ttl-minutes.
kubeconfig-generate-token	If true, automatically generate tokens when a user downloads a kubeconfig.

auth-user-session-ttl-minutes

Time to live (TTL) duration in minutes, used to determine when a user auth session token expires. When expired, the user must log in and obtain a new token. This setting is not affected by auth-token-max-ttl-minutes. Session tokens are created when a user logs into Rancher.

kubeconfig-default-token-ttl-minutes

Time to live (TTL) duration in minutes, used to determine when a kubeconfig token expires. When the token is expired, the API rejects the token. This setting can't be larger than auth-token-max-ttl-minutes. This setting applies to tokens generated in a requested kubeconfig file, except for tokens generated by Rancher CLI. The default value is 0, which means that tokens never expire. Introduced in version 2.6.6.

kubeconfig-token-ttl-minutes

Time to live (TTL) duration in minutes, used to determine when a kubeconfig token that was generated by the CLI expires. Tokens are generated by the CLI when kubeconfig-generate-token is false. When the token is expired, the API rejects the token. This setting can't be larger than auth-token-max-ttl-minutes. Deprecated since Rancher v2.6.6.

auth-token-max-ttl-minutes

Maximum Time to Live (TTL) in minutes allowed for auth tokens. If a user attempts to create a token with a TTL greater than auth-token-max-ttl-minutes, Rancher sets the token TTL to the value of auth-token-max-ttl-minutes. Auth tokens are tokens created for authenticating API requests. The default value is 0, which means that tokens never expire. Rancher v2.6.6 and later: Applies to all kubeconfig tokens and api tokens.

kubeconfig-generate-token

When true, kubeconfigs requested through the UI contain a valid token. When false, the kubeconfig contains a command that uses the Rancher CLI to prompt the user to log in. The CLI then retrieves and caches a token for the user.