rancher-docs/versioned_docs/version-2.12/api/workflows/tokens.md at 325cb0f4a3f5e8418bff1bdec19fecce16102500

mirror of https://github.com/rancher/rancher-docs.git synced 2026-05-12 16:13:23 +00:00

Files

T

Andreas Kupries 325cb0f4a3 Apply suggestions from code review

Thanks for the review and corrections.

Co-authored-by: Lucas Saintarbor <lucas.saintarbor@suse.com>

2025-07-23 11:46:10 -07:00

3.8 KiB

Raw Blame History

title

title
Tokens

Feature Flag

The Tokens Public API is available for Rancher v2.12.0 and later, and is enabled by default. It can be disabled by setting the ext-tokens feature flag to false as shown in the example kubectl command below:

kubectl patch feature ext-tokens -p '{"spec":{"value":false}}'

Creating a Token

Only a valid and active Rancher user can create a Token, otherwise you will get an error displayed (Error from server (Forbidden)...) when attempting to create a Token.

kubectl create -o jsonpath='{.status.value}' -f -<<EOF
apiVersion: ext.cattle.io/v1
kind: Token
EOF
Error from server (Forbidden): error when creating "STDIN": tokens.ext.cattle.io is forbidden: user system:admin is not a Rancher user

A Token is always created for the user making the request. Attempting to create a Token for a different user, by specifying a different spec.userID, is forbidden and will fail.

The spec.description field can be set to an arbitrary human-readable description of the Tokens purpose. The default value is set to empty.
The spec.kind field can be set to the kind of Token. The value session indicates a login Token. All other values, including the default empty string, indicate some kind of derived Token.

The metadata.name and metadata.generateName fields are ignored and the name of the new Token is automatically generated using the prefix token-.

kubectl create -o jsonpath='{.status.value}' -f -<<EOF
apiVersion: ext.cattle.io/v1
kind: Token
spec:
  description: My Token
EOF

If the spec.ttl is not specified, the Token will be created with the expiration time defined in the auth-token-max-ttl-minutes setting. This is 90 days by default. If spec.ttl is specified, it should be greater than 0 and less than or equal to the value of the auth-token-max-ttl-minutes setting expressed in milliseconds.
```
kubectl create -o jsonpath='{.status.value}' -f -<<EOF
apiVersion: ext.cattle.io/v1
kind: Token
spec:
  ttl: 7200000 # 2 hours
EOF
```

Listing Tokens

Listing previously generated Tokens can be useful in order to clean up Tokens which are no longer needed (e.g., it was issued temporarily). Admins can list all Tokens, while regular users can only see their own.

kubectl get tokens.ext.cattle.io
NAME          KIND   TTL   AGE
token-chjc9          90d   18s
token-6fzgj          90d   16s
token-8nbrm          90d   14s

Use -o wide to get more details:

kubectl get tokens.ext.cattle.io -o wide
NAME          USER         KIND   TTL   AGE   DESCRIPTION
token-chjc9   user-jtghh          90d   24s   example
token-6fzgj   user-jtghh          90d   22s   box
token-8nbrm   user-jtghh          90d   20s   jinx

Viewing a Token

Admins can get any Token, while regular users can only get their own.

kubectl get tokens.ext.cattle.io token-chjc9
NAME          KIND   TTL   AGE
token-chjc9          90d   18s

Use -o wide to get more details:

kubectl get tokens.ext.cattle.io token-chjc9 -o wide
NAME          USER         KIND   TTL   AGE   DESCRIPTION
token-chjc9   user-jtghh          90d   24s   example

Deleting a Token

Admins can delete any Token, while regular users can only delete their own.

kubectl delete tokens.ext.cattle.io token-chjc9
token.ext.cattle.io "token-chjc9" deleted

Updating a Token

Only the metadata fields spec.description, spec.ttl, and spec.enabled can be updated. All other spec fields are immutable. Admins are able to extend the spec.ttl field, while regular users can only reduce the value.

An example kubectl command to edit a Token:

kubectl edit tokens.ext.cattle.io token-zp786

3.8 KiB Raw Blame History