public/rancher-docs
1
0
Fork 0
mirror of https://github.com/rancher/rancher-docs.git synced 2026-09-28 14:08:55 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add Tokens example workflows page

Browse Source
This commit is contained in:
Andreas Kupries
2025-07-23 11:45:58 -07:00
committed by Billy Tat
parent 6b577eeacf
commit 28d6a8ff1c
1 changed files with 130 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/api/workflows/tokens.md
+130
View File
@@ -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"}}'
```