Authentication

The Kubiya API uses API keys for authentication. All API requests must include a valid API key in the Authorization header.

Getting an API Key

API keys can be generated from the Kubiya web interface:

1. Log in to your Kubiya account
2. Navigate to Settings > API Keys
3. Click Create New Key
4. Give your key a name and select the appropriate permissions
5. Click Generate Key
6. Copy the key immediately, as it will only be shown once

You can also generate an API key using the CLI:

# Login interactively first
kubiya auth login
 
# View your current API key
kubiya config view

Using Your API Key

Include your API key in the Authorization header of each API request:

Authorization: UserKey YOUR_API_KEY

Note that unlike many other APIs, Kubiya uses the UserKey prefix instead of Bearer for API keys.

Example Request

GET /v1/agents HTTP/1.1
Host: api.kubiya.ai
Authorization: UserKey k1_abcdef123456...
Accept: application/json

API Endpoints

The base URL for all API endpoints is:

https://api.kubiya.ai/v1

Note that the actual API version path may differ from what you see in response URLs.

API Key Best Practices

For production environments, we recommend following these best practices:

1. Use API keys with the minimal required permissions
2. Store keys securely (e.g., in environment variables or a secrets manager)
3. Rotate keys regularly
4. Monitor key usage for suspicious activity
5. Revoke keys immediately if they are compromised

Example Authentication Request

# Making an authenticated request to list teammates
curl -X GET "https://api.kubiya.ai/v1/agents" \
  -H "Authorization: UserKey YOUR_API_KEY" \
  -H "Content-Type: application/json"

Error Responses

If authentication fails, you'll receive a 401 Unauthorized response:

{
  "error": "Authentication failed",
  "details": "Invalid or expired API key",
  "errorCode": "AUTH_REQUIRED"
}

Common authentication errors:

Next Steps

Now that you understand how to authenticate with the Kubiya API, you can explore other API endpoints:

• Agents (Teammates) - Manage AI teammates
• Sources - Manage tool sources
• Agentic Tools - Create and use tools
• Runners - Deploy and manage runners
• Knowledge - Manage knowledge sources
• Webhooks - Set up event notifications