Authentication

The Kubiya CLI authenticates with the Control Plane using API keys. This guide covers authentication setup, configuration management, and best practices.

Quick Setup

Get Your API Key

Via Composer (Web UI)
- Navigate to https://compose.kubiya.ai
- Go to Settings → API Keys
- Click Generate New API Key
- Copy your key (it will only be shown once)

Via API

curl -X POST https://control-plane.kubiya.ai/api/v1/auth/keys \
  -H "Authorization: Bearer $EXISTING_TOKEN" \
  -d '{"name": "cli-key", "ttl": "365d"}'

Configure the CLI

Environment Variable (Recommended)
Config File
Per-Command

# Add to ~/.bashrc, ~/.zshrc, or ~/.profile
export KUBIYA_API_KEY="kby_your_api_key_here"

# Reload shell
source ~/.bashrc

# Create config directory
mkdir -p ~/.kubiya

# Create config file
cat > ~/.kubiya/config.yaml <<EOF
api_key: kby_your_api_key_here
base_url: https://api.kubiya.ai/api/v1
control_plane_url: https://control-plane.kubiya.ai
EOF

# Pass API key with command
kubiya --api-key="kby_your_api_key_here" agent list

Verify Authentication

# Test connection
kubiya agent list

# Check authentication status
kubiya auth status

Expected output:

✅ Authenticated
Organization: your-org
User: you@company.com
Control Plane: https://control-plane.kubiya.ai

Configuration Options

Environment Variables

KUBIYA_API_KEY

string

required

Your Kubiya API authentication key. Get this from the Composer UI or API.

KUBIYA_BASE_URL

string

default:"https://api.kubiya.ai/api/v1"

Base URL for Kubiya API endpoints

CONTROL_PLANE_URL

string

default:"https://control-plane.kubiya.ai"

Control Plane URL for worker registration and management

CONTROL_PLANE_GATEWAY_URL

string

Override for Control Plane URL (takes precedence over CONTROL_PLANE_URL)

KUBIYA_DEBUG

boolean

default:"false"

Enable debug logging for troubleshooting

KUBIYA_LOG_LEVEL

string

default:"INFO"

Set logging verbosity: DEBUG, INFO, WARN, ERROR

Configuration File

Create ~/.kubiya/config.yaml:

# Authentication
api_key: kby_your_api_key_here

# Control Plane URLs
base_url: https://api.kubiya.ai/api/v1
control_plane_url: https://control-plane.kubiya.ai

# Optional: Override control plane URL
# control_plane_gateway_url: https://custom-cp.example.com

# Default settings
default_runner: production-runner
default_environment: production

# Debug options
debug: false
log_level: INFO

# Timeouts (in seconds)
timeout:
  api: 30
  workflow: 3600

Priority Order

The CLI resolves configuration in this order (highest to lowest priority):

Command-line flags (--api-key, --base-url)
Environment variables (KUBIYA_API_KEY, CONTROL_PLANE_URL)
Configuration file (~/.kubiya/config.yaml)
Default values

Example:

# Environment variable
export KUBIYA_API_KEY="key1"

# Override with command flag
kubiya --api-key="key2" agent list  # Uses "key2"

Control Plane Connection

Understanding the Control Plane

The Control Plane is the central management and orchestration layer that:

Manages all platform resources (agents, teams, projects)
Coordinates workflow execution via Temporal
Handles worker registration and health monitoring
Provides event streaming and session persistence
Enforces policies and access control

Control Plane Operations

Resource Management

# List all agents
kubiya agent list

# Create a new agent
kubiya agent create --name "DevOps Agent" --desc "Handles automation tasks"

# List teams
kubiya team list

# List projects
kubiya project list

# List environments
kubiya environment list

Worker Registration

# Start a worker (registers with control plane)
kubiya worker start --queue-id=my-queue --type=local

# Worker automatically:
# 1. Registers with control plane
# 2. Receives Temporal credentials
# 3. Starts polling for tasks
# 4. Sends health heartbeats

Workflow Execution

# Execute workflow (control plane orchestrates)
kubiya workflow execute myorg/deployment.yaml

# Control plane:
# 1. Validates permissions
# 2. Creates Temporal workflow
# 3. Distributes to workers
# 4. Tracks execution

Custom Control Plane

For on-premise or custom deployments:

# Set custom control plane URL
export CONTROL_PLANE_GATEWAY_URL="https://control-plane.company.internal"

# Verify connection
kubiya auth status

# Start worker with custom control plane
kubiya worker start --queue-id=internal-queue --type=local

Multi-Environment Configuration

Using Environment-Specific Keys

Development
Staging
Production

# ~/.kubiya/dev.env
export KUBIYA_API_KEY="kby_dev_key"
export KUBIYA_BASE_URL="https://dev-api.kubiya.ai/api/v1"
export CONTROL_PLANE_URL="https://dev-control-plane.kubiya.ai"
export KUBIYA_DEBUG=true

# Load with:
source ~/.kubiya/dev.env

# ~/.kubiya/staging.env
export KUBIYA_API_KEY="kby_staging_key"
export KUBIYA_BASE_URL="https://staging-api.kubiya.ai/api/v1"
export CONTROL_PLANE_URL="https://staging-control-plane.kubiya.ai"
export KUBIYA_LOG_LEVEL="INFO"

# Load with:
source ~/.kubiya/staging.env

# ~/.kubiya/prod.env
export KUBIYA_API_KEY="kby_prod_key"
export KUBIYA_BASE_URL="https://api.kubiya.ai/api/v1"
export CONTROL_PLANE_URL="https://control-plane.kubiya.ai"
export KUBIYA_LOG_LEVEL="WARN"

# Load with:
source ~/.kubiya/prod.env

Environment Switcher Script

Create ~/.kubiya/switch-env.sh:

#!/bin/bash

ENV=$1

if [ -z "$ENV" ]; then
  echo "Usage: switch-env.sh [dev|staging|prod]"
  exit 1
fi

ENV_FILE="$HOME/.kubiya/${ENV}.env"

if [ ! -f "$ENV_FILE" ]; then
  echo "Environment file not found: $ENV_FILE"
  exit 1
fi

source "$ENV_FILE"
echo "✅ Switched to $ENV environment"
kubiya auth status

Usage:

chmod +x ~/.kubiya/switch-env.sh
~/.kubiya/switch-env.sh dev

Security Best Practices

API Key Management

Never commit API keys to version control or share them in plain text.

Do:

✅ Store keys in environment variables
✅ Use secrets management tools (Vault, AWS Secrets Manager)
✅ Rotate keys regularly
✅ Use short-lived keys for CI/CD
✅ Restrict key permissions to minimum required

Don’t:

❌ Commit keys to Git repositories
❌ Share keys via email or chat
❌ Use the same key across environments
❌ Store keys in application code
❌ Use overly permissive keys

Key Rotation

# Generate new key (via Composer or API)
NEW_KEY="kby_new_key_here"

# Update environment
export KUBIYA_API_KEY="$NEW_KEY"

# Update config file
sed -i "s/api_key:.*/api_key: $NEW_KEY/" ~/.kubiya/config.yaml

# Test new key
kubiya auth status

# Revoke old key via Composer

CI/CD Integration

Store keys as secrets in your CI/CD platform:

GitHub Actions
GitLab CI
Jenkins

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Run Kubiya Command
        env:
          KUBIYA_API_KEY: ${{ secrets.KUBIYA_API_KEY }}
        run: |
          kubiya workflow execute deployment.yaml

deploy:
  script:
    - kubiya workflow execute deployment.yaml
  variables:
    KUBIYA_API_KEY: $KUBIYA_API_KEY

pipeline {
  agent any
  environment {
    KUBIYA_API_KEY = credentials('kubiya-api-key')
  }
  stages {
    stage('Deploy') {
      steps {
        sh 'kubiya workflow execute deployment.yaml'
      }
    }
  }
}

Network Security

For restricted environments:

# Whitelist these endpoints in your firewall
# - https://control-plane.kubiya.ai (Control Plane API)
# - https://api.kubiya.ai (Platform API)
# - Temporal Cloud endpoints (provided during worker setup)

# Test connectivity
curl -I https://control-plane.kubiya.ai/health
curl -I https://api.kubiya.ai/health

Troubleshooting

Authentication Failed

# Check if API key is set
echo $KUBIYA_API_KEY

# Verify key format (should start with "kby_")
# Test authentication
kubiya auth status

# Enable debug logging
export KUBIYA_DEBUG=true
kubiya agent list

Connection Refused

# Check control plane URL
echo $CONTROL_PLANE_URL

# Test connectivity
curl -v https://control-plane.kubiya.ai/health

# Check for proxy settings
echo $HTTP_PROXY
echo $HTTPS_PROXY

# Try with custom DNS
ping control-plane.kubiya.ai

SSL Certificate Errors

# Update CA certificates
# Ubuntu/Debian
sudo apt-get update && sudo apt-get install ca-certificates

# macOS
brew install ca-certificates

# Verify certificates
openssl s_client -connect control-plane.kubiya.ai:443

Invalid API Key Format

API keys must:

Start with kby_
Be alphanumeric with underscores
Have minimum length requirements

# Valid format
KUBIYA_API_KEY="kby_abc123def456..."

# Invalid formats
KUBIYA_API_KEY="abc123"  # Missing prefix
KUBIYA_API_KEY="kby-abc123"  # Wrong separator

Command Reference

# Check authentication status
kubiya auth status

# List available organizations
kubiya org list

# Switch organization (if you have access to multiple)
kubiya org use <org-id>

# Display current configuration
kubiya config show

# Validate configuration
kubiya config validate

Next Steps

Worker Management

Deploy and manage workers on your infrastructure

Control Plane Resources

Learn to manage agents, teams, and other resources

Workflow Execution

Execute automated workflows via the control plane

Environment Variables

Complete reference of all configuration options

Getting Started

On-Demand Execution

Control Plane

Control Plane Resources

Context Graph

Cognitive Memory

Advanced

​Quick Setup

​Get Your API Key

​Configure the CLI

​Verify Authentication

​Configuration Options

​Environment Variables

​Configuration File

​Priority Order

​Control Plane Connection

​Understanding the Control Plane

​Control Plane Operations

​Resource Management

​Worker Registration

​Workflow Execution

​Custom Control Plane

​Multi-Environment Configuration

​Using Environment-Specific Keys

​Environment Switcher Script

​Security Best Practices

​API Key Management

​Key Rotation

​CI/CD Integration

​Network Security

​Troubleshooting

​Authentication Failed

​Connection Refused

​SSL Certificate Errors

​Invalid API Key Format

​Command Reference

​Next Steps

Worker Management

Control Plane Resources

Workflow Execution

Environment Variables

Quick Setup

Get Your API Key

Configure the CLI

Verify Authentication

Configuration Options

Environment Variables

Configuration File

Priority Order

Control Plane Connection

Understanding the Control Plane

Control Plane Operations

Resource Management

Worker Registration

Workflow Execution

Custom Control Plane

Multi-Environment Configuration

Using Environment-Specific Keys

Environment Switcher Script

Security Best Practices

API Key Management

Key Rotation

CI/CD Integration

Network Security

Troubleshooting

Authentication Failed

Connection Refused

SSL Certificate Errors

Invalid API Key Format

Command Reference

Next Steps