Skip to Content
UsersUser ManagementAPI Keys

API Keys
Available in v1.32.6+

API keys let you authenticate programmatically against the ScaleOps REST API and MCP server without a browser session. Keys carry scoped RBAC rules and support expiration.

API Keys list

Authentication

Pass the key as a Bearer token or via Basic Auth (username is ignored):

# Bearer token — e.g. list all clusters
curl -H "Authorization: Bearer $API_KEY" \
  "https://<DASHBOARD_URL>/api/v1/clusters"
 
# Basic Auth
curl -u "user:$API_KEY" \
  "https://<DASHBOARD_URL>/api/v1/clusters"

Managing Keys (UI)

Go to Users → API Keys and click Create API Key.

Create API Key dialog

The raw key is shown once immediately after creation — copy it now.

API key created — copy now

GitOps (Self-Hosted Only)

Provision static keys at deploy time via Helm values.

Step 1 — Generate a Hash

Self-hosted ScaleOps stores key hashes using SHA-256. Generate the hash before adding it to your Helm values:

# Generate a random key
RAW_KEY="so_sl_$(openssl rand -base64 32 | tr -d '=+/' | head -c 40)"
echo "Raw key (store securely): $RAW_KEY"
 
# Hash it with SHA-256
HASH=$(echo -n "$RAW_KEY" | sha256sum | awk '{print $1}')
# or on macOS:
# HASH=$(echo -n "$RAW_KEY" | shasum -a 256 | awk '{print $1}')
echo "Hashed key (apply in Helm chart): $HASH"

Python equivalent:

import hashlib, secrets, base64
 
raw = "so_sl_" + base64.urlsafe_b64encode(secrets.token_bytes(32)).rstrip(b"=").decode()
hash_value = hashlib.sha256(raw.encode()).hexdigest()
print("Raw key:", raw)
print("SHA-256 hash:", hash_value)

Step 2 — Configure Helm Values

apiKeys:
  keys:
    - name: ci-pipeline
      hash: <sha256-hash-of-key>
      expire: "2027-01-01T00:00:00Z"   # RFC3339 UTC — omit for no expiry
      rule:
        role: Admin
    - name: monitoring-readonly
      hash: <sha256-hash-of-key>
      # no expire field — key never expires
      rule:
        role: Viewer
        targetNamespaces:
          - namespaceNames: ["monitoring", "observability"]
    - name: team-a-operator
      hash: <sha256-hash-of-key>
      expire: "2026-12-31T23:59:59Z"
      rule:
        role: Operator
        targetNamespaces:
          - namespaceNames: ["team-a", "team-a-staging"]

External Secret

apiVersion: v1
kind: Secret
metadata:
  name: scaleops-api-keys   # override with apiKeys.secretName in Helm values
  namespace: scaleops
stringData:
  keys: |
    - name: ci-pipeline
      hash: <sha256-hash-of-key>
      rule:
        role: Admin

RBAC Scoping

Omit scope fields to grant the role across all clusters and namespaces.

Operator scoped to two namespaces:

{
  "name": "team-a-operator",
  "expire": "1y",
  "rule": {
    "role": "Operator",
    "targetNamespaces": [
      { "namespaceNames": ["team-a", "team-a-staging"] }
    ]
  }
}

Viewer scoped by label selector:

{
  "name": "monitoring-viewer",
  "expire": "90d",
  "rule": {
    "role": "Viewer",
    "targetNamespaces": [
      {
        "namespaceNames": [],
        "labelSelector": { "matchLabels": { "team": "platform" } }
      }
    ]
  }
}

Admin on specific clusters only:

{
  "name": "prod-admin",
  "expire": "1y",
  "rule": {
    "role": "Admin",
    "targetClusters": ["cluster-name1", "cluster-name2"]
  }
}
AuthorizationSelf-Hosted