Add Tokens example workflows page

2026-09-24 20:18:18 +00:00 · 2025-07-23 11:45:58 -07:00
parent 6b577eeacf
commit 28d6a8ff1c
1 changed files with 130 additions and 0 deletions
@@ -0,0 +1,130 @@
+---
+title: Tokens
+---
+
+<head>
+    <link rel="canonical" href="https://ranchermanager.docs.rancher.com/api/workflows/tokens"/>
+</head>
+
+## Feature Flag
+
+The Tokens Public API is available since Rancher v2.12.0 and is enabled by default.
+It can be disabled by setting the `ext-tokens` feature flag to `false`.
+
+```sh
+kubectl patch feature ext-tokens -p '{"spec":{"value":false}}'
+```
+
+## Creating a Token
+
+Only a **valid and active** Rancher user can create a Token.
+
+```bash
+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 (purpose of the) token.
+The default is empty.
+
+The `spec.kind` field can be set to the kind of token.
+The value "session" indicates a login token.
+All other kinds, including the default (empy string) indicate some kind of derived token.
+
+The `name` and `generateName` fields of the new token are ignored. The system automatically choosen a name using the prefix `token-`.
+
+```bash
+kubectl create -o jsonpath='{.status.value}' -f -<<EOF
+apiVersion: ext.cattle.io/v1
+kind: Token
+spec:
+  description: My Token
+EOF
+```
+
+If `spec.ttl` is not specified, the tokens 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.
+
+```bash
+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.
+
+```sh
+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:
+
+```sh
+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.
+
+```sh
+kubectl get tokens.ext.cattle.io token-chjc9
+NAME          KIND   TTL   AGE
+token-chjc9          90d   18s
+```
+
+Use `-o wide` to get more details:
+
+```sh
+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.  
+
+```sh
+kubectl delete tokens.ext.cattle.io token-chjc9
+token.ext.cattle.io "token-chjc9" deleted
+```
+
+
+#### Updating a Token
+
+Only the metadata, the `spec.description` field, the `spec.ttl` field, and the `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.
+
+To add a label to a Token:
+
+```sh
+kubectl patch token token-zp786 -p '{"metadata":{"labels":{"foo":"bar"}}}'
+```
+
+To change the description of a Token:
+
+```sh
+kubectl patch token token-zp786 -p '{"spec":{"description":"Updated description"}}'
+```