API Authentication

Authenticate with the Rancher API using tokens and bearer authentication

Rancher API uses token-based authentication to secure API access. All API requests must include a valid authentication token.

Authentication Methods

Bearer Token Authentication

The primary authentication method uses bearer tokens in the Authorization header:

curl -H "Authorization: Bearer token-xxxxx:xxxxxxxxxxxxxxxx" \
  https://rancher-server/v3/clusters

Basic Authentication

Basic authentication can be used for initial token generation:

curl -u "username:password" \
  https://rancher-server/v3-public/localProviders/local?action=login

Token Types

Rancher supports multiple token types for different use cases.

User Tokens

User tokens are associated with a specific user account:

userId · string · required

The ID of the user who owns this token

authProvider · string · required

Authentication provider (local, github, activedirectory, etc.)

ttl · integer

Token TTL in milliseconds. 0 means never expires

enabled · boolean · default: "true"

Whether the token is enabled and can be used

description · string

Human-readable description of the token’s purpose

Service Account Tokens

Service account tokens are used for automated workflows:

accountName · string · required

Name of the service account

accountUid · string

UID of the service account

token · string

The actual token value (only returned on creation)

Creating API Tokens

Create User Token via UI

1. Navigate to User Settings > API & Keys
2. Click Add Key
3. Set description and expiration
4. Save the token securely (shown only once)

Create Token via API

cURL

curl -X POST \
  -H "Authorization: Bearer <existing-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "token",
    "description": "CI/CD Pipeline Token",
    "ttl": 0
  }' \
  https://rancher-server/v3/tokens

Response

token · string

The authentication token value. Save this securely - it won’t be shown again.

id · string

Unique identifier for the token

userId · string

ID of the user who owns this token

expiresAt · string

ISO 8601 timestamp when the token expires

userPrincipal · object

Principal information for the token owner

Token Management

List Tokens

Retrieve all tokens for the authenticated user:

curl -H "Authorization: Bearer token-xxxxx:xxxxxxxxxxxxxxxx" \
  https://rancher-server/v3/tokens

Delete Token

Revoke a token:

curl -X DELETE \
  -H "Authorization: Bearer token-xxxxx:xxxxxxxxxxxxxxxx" \
  https://rancher-server/v3/tokens/<token-id>

Update Token

Modify token properties (description, enabled status):

curl -X PUT \
  -H "Authorization: Bearer token-xxxxx:xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated description",
    "enabled": false
  }' \
  https://rancher-server/v3/tokens/<token-id>

Token Security Best Practices

Use Short-Lived Tokens for Automation

Set appropriate TTL values for automated workflows. Tokens for CI/CD should expire after the pipeline completes.

Rotate Tokens Regularly

Implement token rotation policies, especially for long-lived service accounts.

Scope Tokens Appropriately

Use cluster-scoped tokens when possible instead of global admin tokens.

Store Tokens Securely

Never commit tokens to version control. Use secret management systems like:

• Kubernetes Secrets
• HashiCorp Vault
• Cloud provider secret managers

Monitor Token Usage

Track token activity via audit logs to detect suspicious behavior.

Token Attributes

Token Object Schema

From pkg/apis/management.cattle.io/v3/authn_types.go:30:

token · string

The actual token value (write-only, only returned on creation)

userPrincipal · Principal

Principal representing the authenticated user

groupPrincipals · array<Principal>

List of group principals the user belongs to

providerInfo · map<string, string>

Additional information from the authentication provider

userId · string

Reference to the user who owns this token

authProvider · string

Authentication provider (local, github, ldap, etc.)

ttl · integer

Time to live in milliseconds. 0 means never expires.

lastUsedAt · timestamp

Last time the token was used for authentication

isDerived · boolean

Whether this is a derived token (created automatically)

description · string

Human-readable description of the token

expired · boolean

Whether the token has expired

clusterName · string

Cluster scope for cluster-scoped tokens

enabled · boolean · default: "true"

Whether the token is active and can be used

API Access Patterns

Cluster-Scoped Access

Create tokens scoped to specific clusters:

{
  "type": "token",
  "description": "Dev Cluster Access",
  "clusterName": "c-m-abc123",
  "ttl": 86400000
}

Project-Scoped Access

Access resources within a specific project using project membership and RBAC:

curl -H "Authorization: Bearer token-xxxxx:xxxxxxxxxxxxxxxx" \
  https://rancher-server/v3/projects/<project-id>/workloads

Global Access

Global admin tokens can access all resources:

curl -H "Authorization: Bearer token-xxxxx:xxxxxxxxxxxxxxxx" \
  https://rancher-server/v3/clusters

Limit the use of global admin tokens. Use scoped tokens wherever possible.

Troubleshooting Authentication

Common Issues

401 Unauthorized

• Token may have expired
• Token may be disabled
• Authorization header may be malformed
• Check token format: Bearer token-xxxxx:xxxxxxxxxxxxxxxx

403 Forbidden

• User lacks permissions for the requested resource
• Check RBAC roles and bindings
• Verify cluster/project membership

Token Not Working After Creation

• Allow a few seconds for token propagation
• Verify the token was copied correctly
• Check that enabled field is true

Next Steps

Cluster Management

Use your token to manage clusters

RBAC

Learn about role-based access control