---
title: "Mint a cluster token"
method: POST
path: "/v1/kubernetes/clusters/{id}/token"
tags: ["Kubernetes"]
---

# Mint a cluster token

`POST /v1/kubernetes/clusters/{id}/token`

Exchanges the caller's API key or session for a short-lived bearer token that only this cluster accepts, returned as an ExecCredential so a kubectl exec credential plugin can print it as is. The token carries cluster-admin and expires after one hour; mint another rather than storing it. `orl kube token` is such a plugin, and `orl kube kubeconfig` writes a kubeconfig that runs it. A cluster that is deleting or failed answers 409 INVALID_CLUSTER_STATE. A restricted or pending organization can still mint. Needs clusters:write on an API key, or the owner, admin or member role on a session.

## Path parameters

- `id` string, required

## Response `200`

A cluster token

- KubernetesExecCredential — A client.authentication.k8s.io/v1 ExecCredential, the object a kubectl exec credential plugin prints, so a plugin can pass the response through unchanged.
  - `apiVersion` 'client.authentication.k8s.io/v1', required
  - `kind` 'ExecCredential', required
  - `status` KubernetesExecCredentialStatus, required
    - `expirationTimestamp` string, required — When the token expires (RFC 3339). Clients mint a new one after this.
    - `token` string, required — A bearer token only this cluster accepts.

## Other responses

- `401` — Missing or invalid API key
- `403` — The caller is authenticated but may not do this. As on every operation, the caller's role or the API key's scope does not allow it, or the request targets another organization (FORBIDDEN, or NOT_A_MEMBER for a session), or the organization is suspended pending review (ORG_SUSPENDED) or has been deleted (ORG_DISABLED). This operation can also be refused because of the account. A new workload (a VM or pod create, a VM fork, a Kubernetes cluster or node pool create, a node pool scaled up) answers INSUFFICIENT_BALANCE, ACCOUNT_RESTRICTED or ACCOUNT_PENDING_VERIFICATION; a restart or reboot answers INSUFFICIENT_BALANCE; an API key create answers ACCOUNT_RESTRICTED or ACCOUNT_PENDING_VERIFICATION; a deposit or card save answers ACCOUNT_PENDING_VERIFICATION, VERIFICATION_UNAVAILABLE or FUNDING_UNDER_REVIEW; and a runner pool create answers ACCOUNT_PENDING_VERIFICATION. Every gate also answers ACCOUNT_SUSPENDED for a suspended organization, but only platform admins and internal callers reach it: a customer's request for a suspended organization is refused at authentication with ORG_SUSPENDED before it gets to a gate. A new API key or a wider scope clears none of these; see [Account and balance refusals](https://docs.openrelay.inc/docs/errors#account-and-balance-refusals) for what each one means and what to do.
- `404` — Resource not found
- `409` — The request conflicts with existing state

## Changes

- **2026-10-03** `bcf63adad2c3` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/openrelay/apis/openrelay-api/changes/v1/kubernetes/clusters/:id/token/post.md)

---

[API](https://skmtc.dev/openrelay/apis/openrelay-api.md) · [All operations](https://skmtc.dev/openrelay/apis/openrelay-api/llms.txt) · [OpenAPI document](https://skmtc.dev/openrelay/apis/openrelay-api/revisions/bcf63adad2c3?raw)