Some environments and workflows require programmatic or terminal-only access to Kubernetes clusters without relying on browser-based authentication. This is particularly important for CI/CD pipelines, remote systems without a graphical interface, or users working over SSH.

By default, our platform uses OIDC-based authentication, which prompts a login flow through your local browser. While this approach is secure and user-friendly for interactive sessions, it isn't always suitable for automated or headless environments.

## How to use headless access to Syself Autopilot

We provide headless access via a Kubernetes Service Account token. This approach bypasses the OIDC browser flow and enables direct access through a generated kubeconfig file.

The service account we expose is the same one used by GitOps tools that need to make changes to the Management Cluster. By reusing this account, you gain authenticated, stable, and non-interactive access without managing user credentials.

This account is scoped to your organization namespace: it can apply and patch manifests there, such as your `Cluster` declarations, but it is not a cluster-admin. Use it to manage your own resources, not for cluster-wide operations like a `helm install` against the management cluster.

You can generate a `kubeconfig` from this account with the following command:

```console
$ SERVER=$(kubectl config view --minify -o jsonpath='{.clusters[0].cluster.server}') && \
CA_CRT=$(kubectl get secret gitops-sa-secret -o jsonpath='{.data.ca\.crt}') && \
TOKEN=$(kubectl get secret gitops-sa-secret -o jsonpath='{.data.token}' | base64 --decode) && \
cat <<EOF > syself-headless-kubeconfig.yaml
apiVersion: v1
kind: Config
clusters:
- name: syself-autopilot
  cluster:
    certificate-authority-data: $CA_CRT
    server: $SERVER
users:
- name: sa-user
  user:
    token: $TOKEN
contexts:
- name: sa-context
  context:
    cluster: syself-autopilot
    user: sa-user
current-context: sa-context
EOF
```

This will create a `syself-headless-kubeconfig.yaml` file you can use with `kubectl` or in CI/CD pipelines:

```console
$ KUBECONFIG=syself-headless-kubeconfig.yaml kubectl get clusters
```

> [!TIP]
> This is also the kubeconfig you give Argo CD when you add the management cluster as a remote destination. See [Set up Argo CD](/docs/hetzner/apalla/clusters/gitops/set-up-argo-cd).

## Security considerations

This is a persistent token. Unlike OIDC flows that expire and require reauthentication, a service account token does not expire unless manually revoked.

Treat the token like a password. Anyone with access to this kubeconfig has the same permissions as the service account. Store it securely and avoid committing it to version control.

Prefer OIDC for human users. This headless access method is best suited for automation. For human users, browser-based login remains the safest and most auditable path.

## Rotate a compromised token

If the token leaks, revoke it by deleting the `gitops-sa-secret` Secret in the management cluster. A fresh token is issued in its place, and you regenerate the kubeconfig with the command above. Any kubeconfig built from the old token stops working, so update your CI secrets with the new one. If the Secret is not reissued, contact Syself support.

## Related

- [Set up Argo CD](/docs/hetzner/apalla/clusters/gitops/set-up-argo-cd), give this kubeconfig to Argo CD as a remote destination
- [Configure OIDC login](/docs/hetzner/apalla/clusters/configure/configure-oidc), the browser-based login this method replaces for automation