added to sidebar, and imported into 2.12 setup

2026-04-27 00:35:41 +00:00 · 2025-07-14 12:56:22 +02:00
parent e4be1e9d7a
commit 960d68d7c9
3 changed files with 118 additions and 2 deletions
--- a/versioned_docs/version-2.12/api/workflows/tokens.md
+++ b/versioned_docs/version-2.12/api/workflows/tokens.md
@@ -0,0 +1,114 @@
+---
+title: Tokens
+---
+
+<head>
+    <link rel="canonical" href="https://ranchermanager.docs.rancher.com/api/workflows/tokens"/>
+</head>
+
+## 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:
+
+```sh
+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.
+
+```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 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-`.
+
+	```bash
+	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.
+
+	```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
+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.
+
+```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 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:
+
+```sh
+kubectl edit tokens.ext.cattle.io token-zp786