> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kubiya.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API Keys

> Generate and manage API keys for programmatic access

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

<Warning>
  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.
</Warning>

### Key Details

Each key displays:

| Field         | Description              |
| ------------- | ------------------------ |
| **Name**      | Descriptive identifier   |
| **Created**   | Creation timestamp       |
| **Last Used** | Most recent API call     |
| **Expires**   | Expiration date (if set) |
| **Status**    | Active 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

```python theme={null}
from kubiya import Client

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

### CLI Authentication

```bash theme={null}
export KUBIYA_API_KEY="your-api-key-here"
kubiya agents list
```

Or pass directly:

```bash theme={null}
kubiya --api-key "your-api-key-here" agents list
```

### HTTP Headers

For direct API calls:

```bash theme={null}
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

<Tip>
  For CI/CD systems, use environment variables or secrets management:

  ```yaml theme={null}
  # GitHub Actions example
  env:
    KUBIYA_API_KEY: ${{ secrets.KUBIYA_API_KEY }}
  ```
</Tip>

## 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

## Related Pages

* **[SDK Overview](/sdk/overview)** - Using the Kubiya SDK
* **[CLI Authentication](/cli/authentication)** - CLI setup
* **[API Reference](/api-reference/overview)** - Direct API access