Skip to main content
API keys enable programmatic access to the Kubiya platform. Use them for:
  • SDK authentication
  • CLI authentication
  • CI/CD integrations
  • Custom automation

​
Access

Navigate to Settings > API Keys or directly to /settings#apiKeys.

​
Managing API Keys

​
Creating a Key

  1. Click + Generate New Key
  2. Enter a descriptive name (e.g., “CI/CD Pipeline”, “Local Development”)
  3. Set an optional expiration date
  4. Click Generate
  5. Copy the key immediately - it won’t be shown again
API keys are shown only once upon creation. Store them securely in a password manager or secrets vault. If lost, you must revoke and create a new key.

​
Key Details

Each key displays:
FieldDescription
NameDescriptive identifier
CreatedCreation timestamp
Last UsedMost recent API call
ExpiresExpiration date (if set)
StatusActive or Revoked

​
Revoking a Key

  1. Find the key in the list
  2. Click the Revoke button
  3. Confirm revocation
Revoked keys stop working immediately. Any applications using them will receive authentication errors.

​
Using API Keys

​
SDK Authentication

from kubiya import Client

client = Client(api_key="your-api-key-here")

​
CLI Authentication

export KUBIYA_API_KEY="your-api-key-here"
kubiya agents list
Or pass directly: 
kubiya --api-key "your-api-key-here" agents list

​
HTTP Headers

For direct API calls: 
curl -H "Authorization: Bearer your-api-key-here" \
  https://control-plane.kubiya.ai/api/v1/agents

​
Best Practices

​
Key Naming

Use descriptive names that identify:
  • Purpose: “CI/CD Pipeline”, “Monitoring Integration”
  • Environment: “Production Terraform”, “Development CLI”
  • Owner: “DevOps Team Key”, “John’s Local Dev”

​
Key Rotation

Rotate keys periodically:
  1. Create a new key with a similar name
  2. Update applications to use the new key
  3. Verify the new key works
  4. Revoke the old key

​
Scope and Permissions

API keys inherit the permissions of the user who created them. For limited-scope access:
  • Create keys from service accounts with restricted permissions
  • Use separate keys for different integration needs

​
Security

  • Never commit API keys to version control
  • Use environment variables or secrets managers
  • Set expiration dates for temporary access
  • Revoke keys when no longer needed
For CI/CD systems, use environment variables or secrets management:
# GitHub Actions example
env:
  KUBIYA_API_KEY: ${{ secrets.KUBIYA_API_KEY }}

​
Troubleshooting

​
”Invalid API Key” Error

  • Verify the key is copied correctly (no extra spaces)
  • Check if the key has been revoked
  • Confirm the key hasn’t expired
  • Ensure the key belongs to the correct control plane

​
”Unauthorized” Error

  • The key may lack permissions for the requested action
  • Check if your user account has the required permissions
  • Contact your administrator for permission changes