Authentication

All Kaman API requests require authentication. This guide covers the available authentication methods.

Authentication Methods

API Key (Recommended for Server-Side)

API keys are the recommended method for server-to-server integrations. API keys start with kam_ prefix.

bash

curl -X GET "http://kaman.ai/api/agent/workflows" \
  -H "Authorization: Bearer kam_your_api_key"

JWT Token (For User Sessions)

For applications with user sessions, use JWT tokens obtained from the auth service.

bash

curl -X GET "http://kaman.ai/api/agent/workflows" \
  -H "Authorization: Bearer JWT_TOKEN"

Creating API Keys

Via Marketplace UI

Log in to the Kaman Marketplace
Go to Settings > API Keys
Click Create New Key
Give your key a descriptive name
Copy the key immediately (it won't be shown again)

API keys start with kam_ and look like: kam_abc123xyz...

API Key Best Practices

Security

Never expose API keys in client-side code
Store keys in environment variables or secure vaults
Use different keys for development and production
Rotate keys periodically

Environment Variables

bash

# .env file
KAMAN_API_KEY=kam_your_api_key_here

typescript

// In your code
const apiKey = process.env.KAMAN_API_KEY;

Error Responses

401 Unauthorized

json

{
  "error": "Invalid or missing authentication token"
}

Causes:

Missing Authorization header
Expired token
Invalid API key

403 Forbidden

json

{
  "error": "Access denied to this resource"
}

Causes:

API key doesn't have permission for this resource
Resource belongs to a different client

Code Examples

TypeScript

typescript

import axios from 'axios';

const client = axios.create({
  baseURL: 'http://kaman.ai/api/agent',
  headers: {
    'Authorization': `Bearer ${process.env.KAMAN_API_KEY}`,
    'Content-Type': 'application/json'
  }
});

// Make authenticated requests
const workflows = await client.get('/workflows');

Python

python

import requests
import os

class KamanClient:
    def __init__(self, base_url: str):
        self.base_url = f'{base_url}/api/agent'
        self.headers = {
            'Authorization': f'Bearer {os.getenv("KAMAN_API_KEY")}',
            'Content-Type': 'application/json'
        }

    def get_workflows(self):
        response = requests.get(
            f'{self.base_url}/workflows',
            headers=self.headers
        )
        return response.json()

# Usage
client = KamanClient('http://kaman.ai')
workflows = client.get_workflows()

cURL

bash

#!/bin/bash
API_KEY="${KAMAN_API_KEY}"
BASE_URL="http://kaman.ai/api/agent"

# GET request
curl -s "$BASE_URL/workflows" \
  -H "Authorization: Bearer $API_KEY"

# POST request
curl -s -X POST "$BASE_URL/workflows/123/execute" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"param1": "value1"}'

Troubleshooting

Common Issues

"Invalid token" errors
- Verify the token hasn't expired
- Check for extra whitespace in the header
- Ensure the token is correctly copied
- Verify the token starts with kam_ for API keys
"Access denied" errors
- Verify the API key has access to the resource
- Check if the resource belongs to your client
CORS errors (browser)
- API keys should not be used in browser code
- Use a backend proxy for API calls

Next Steps

Getting Started - Quick start guide
Workflows API - Execute and manage workflows
KDL API - Query your data lake

Authentication

All Kaman API requests require authentication. This guide covers the available authentication methods.

Authentication Methods

API Key (Recommended for Server-Side)

API keys are the recommended method for server-to-server integrations. API keys start with kam_ prefix.

bash

curl -X GET "http://kaman.ai/api/agent/workflows" \
  -H "Authorization: Bearer kam_your_api_key"

JWT Token (For User Sessions)

For applications with user sessions, use JWT tokens obtained from the auth service.

bash

curl -X GET "http://kaman.ai/api/agent/workflows" \
  -H "Authorization: Bearer JWT_TOKEN"

Creating API Keys

Via Marketplace UI

Log in to the Kaman Marketplace
Go to Settings > API Keys
Click Create New Key
Give your key a descriptive name
Copy the key immediately (it won't be shown again)

API keys start with kam_ and look like: kam_abc123xyz...

API Key Best Practices

Security

Never expose API keys in client-side code
Store keys in environment variables or secure vaults
Use different keys for development and production
Rotate keys periodically

Environment Variables

bash

# .env file
KAMAN_API_KEY=kam_your_api_key_here

typescript

// In your code
const apiKey = process.env.KAMAN_API_KEY;

Error Responses

401 Unauthorized

json

{
  "error": "Invalid or missing authentication token"
}

Causes:

Missing Authorization header
Expired token
Invalid API key

403 Forbidden

json

{
  "error": "Access denied to this resource"
}

Causes:

API key doesn't have permission for this resource
Resource belongs to a different client

Code Examples

TypeScript

typescript

import axios from 'axios';

const client = axios.create({
  baseURL: 'http://kaman.ai/api/agent',
  headers: {
    'Authorization': `Bearer ${process.env.KAMAN_API_KEY}`,
    'Content-Type': 'application/json'
  }
});

// Make authenticated requests
const workflows = await client.get('/workflows');

Python

python

import requests
import os

class KamanClient:
    def __init__(self, base_url: str):
        self.base_url = f'{base_url}/api/agent'
        self.headers = {
            'Authorization': f'Bearer {os.getenv("KAMAN_API_KEY")}',
            'Content-Type': 'application/json'
        }

    def get_workflows(self):
        response = requests.get(
            f'{self.base_url}/workflows',
            headers=self.headers
        )
        return response.json()

# Usage
client = KamanClient('http://kaman.ai')
workflows = client.get_workflows()

cURL

bash

#!/bin/bash
API_KEY="${KAMAN_API_KEY}"
BASE_URL="http://kaman.ai/api/agent"

# GET request
curl -s "$BASE_URL/workflows" \
  -H "Authorization: Bearer $API_KEY"

# POST request
curl -s -X POST "$BASE_URL/workflows/123/execute" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"param1": "value1"}'

Troubleshooting

Common Issues

"Invalid token" errors
- Verify the token hasn't expired
- Check for extra whitespace in the header
- Ensure the token is correctly copied
- Verify the token starts with kam_ for API keys
"Access denied" errors
- Verify the API key has access to the resource
- Check if the resource belongs to your client
CORS errors (browser)
- API keys should not be used in browser code
- Use a backend proxy for API calls

Next Steps

Getting Started - Quick start guide
Workflows API - Execute and manage workflows
KDL API - Query your data lake