You are viewing documentation for Cozystack v1, which is currently in beta. For the latest stable version, see the v0 documentation.

ServiceAccount Tokens for API Access

How to retrieve and use ServiceAccount tokens in Cozystack.

Prerequisites

Before you begin, make sure that:

  • A tenant already exists in Cozystack. See Create a User Tenant if you haven’t created one yet.
  • You have access to the tenant namespace — either via OIDC credentials or an administrative kubeconfig.
  • kubectl is installed and configured.
  • (Optional) jq is installed.

Retrieving the ServiceAccount Token

Each tenant in Cozystack has a Secret that contains a ServiceAccount token. The Secret has the same name as the tenant and is located in the tenant’s namespace.

  1. Log in to the Dashboard as a user with access to the tenant.
  2. Switch context to the target tenant if needed.
  3. On the left sidebar, navigate to the Administration → Info page and open the Secrets tab.
  4. Find the secret named tenant-<name> (e.g. tenant-team1), where the Key is token.
  5. Click the eye icon to reveal the Value field, then click the revealed data. The text will be copied to the clipboard automatically.

Retrieve the token for a tenant named <name>:

kubectl -n tenant-<name> get tenantsecret tenant-<name> -o json | jq -r '.data.token | @base64d'

To store the token in a variable for subsequent commands:

export TOKEN=$(kubectl -n tenant-<name> get tenantsecret tenant-<name> -o json | jq -r '.data.token | @base64d')

Using the Token for API Access

Once you have the token, you can generate a kubeconfig for kubectl access, or use it directly with curl as shown below.

Test the Connection

First, verify your kubectl context points to the correct Cozystack cluster:

kubectl config current-context
kubectl cluster-info

Next, get the API server address:

export API_SERVER=$(kubectl config view --minify -o jsonpath='{.clusters[0].cluster.server}')

Then, extract the CA certificate from the tenant secret:

kubectl -n tenant-<name> get secret tenant-<name> -o jsonpath='{.data.ca\.crt}' | base64 -d > ca.crt

Now, test the connection:

curl --cacert ca.crt -H "Authorization: Bearer ${TOKEN}" ${API_SERVER}/api

You can remove ca.crt after testing.

Last modified 2026-02-17: improve serviceaccount-api-access clarity and consistency (0406f6e)