​
Authentication Methods

The Kaie API supports multiple authentication methods to secure your API requests and ensure only authorized access to your workflows and data.

​
API Key Authentication

The most common method for authenticating with the Kaie API is using API keys.

​
Getting Your API Key

  1. Log in to your Kaie dashboard
  2. Navigate to Settings > API Keys
  3. Click Create New API Key
  4. Give your key a descriptive name
  5. Select the appropriate permissions
  6. Copy the generated API key
API keys are only shown once when created. Make sure to copy and store your API key securely.

​
Using API Keys

Include your API key in the Authorization header of your requests: 
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.kaie.ai/v1/workflows

​
API Key Permissions

API keys can be configured with different permission levels:

​
OAuth 2.0 Authentication

For applications that need to access user data on behalf of users, OAuth 2.0 is recommended.

​
OAuth Flow

  1. Authorization Request: Redirect users to the authorization endpoint
  2. User Consent: Users grant permission to your application
  3. Authorization Code: Receive an authorization code
  4. Token Exchange: Exchange the code for access and refresh tokens
  5. API Access: Use the access token to make API requests

​
Authorization Endpoint

GET https://api.kaie.ai/oauth/authorize
Parameters:
  • client_id: Your application’s client ID
  • redirect_uri: Where to redirect after authorization
  • response_type: Must be code
  • scope: Requested permissions (space-separated)
  • state: Random string to prevent CSRF attacks

​
Token Endpoint

POST https://api.kaie.ai/oauth/token
Parameters:
  • grant_type: Must be authorization_code
  • code: Authorization code from the previous step
  • redirect_uri: Same redirect URI used in authorization
  • client_id: Your application’s client ID
  • client_secret: Your application’s client secret

​
Using Access Tokens

Include the access token in the Authorization header: 
curl -H "Authorization: Bearer ACCESS_TOKEN" \
  https://api.kaie.ai/v1/workflows

​
Refresh Tokens

Access tokens expire after 1 hour. Use refresh tokens to get new access tokens: 
curl -X POST https://api.kaie.ai/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token&refresh_token=REFRESH_TOKEN&client_id=CLIENT_ID&client_secret=CLIENT_SECRET"

​
JWT Authentication

For server-to-server communication, JWT (JSON Web Token) authentication is supported.

​
Creating JWT Tokens

JWT tokens must be signed with your private key and include the following claims: 
{
  "iss": "your-application-id",
  "sub": "user-or-service-id",
  "aud": "kaie-api",
  "exp": 1640995200,
  "iat": 1640908800,
  "scope": "workflows:read workflows:write"
}

​
Using JWT Tokens

Include the JWT token in the Authorization header: 
curl -H "Authorization: Bearer JWT_TOKEN" \
  https://api.kaie.ai/v1/workflows

​
Webhook Authentication

Webhooks use HMAC-SHA256 signatures to verify the authenticity of incoming requests.

​
Verifying Webhook Signatures

The webhook signature is included in the X-Kaie-Signature header: 
const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature, 'hex'),
    Buffer.from(expectedSignature, 'hex')
  );
}

​
Rate Limiting

API requests are subject to rate limiting to ensure fair usage and system stability.

​
Rate Limits

  • API Key: 1000 requests per hour
  • OAuth Token: 1000 requests per hour
  • JWT Token: 1000 requests per hour
  • Webhook: 100 requests per minute

​
Rate Limit Headers

Rate limit information is included in response headers: 
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

​
Handling Rate Limits

When you exceed the rate limit, you’ll receive a 429 Too Many Requests response: 
{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded",
    "retry_after": 3600
  }
}
Wait for the specified retry_after seconds before making new requests.

​
Security Best Practices

​
API Key Security

​
Token Security

​
Error Handling

​
Authentication Errors

Common authentication errors and their meanings:
Status CodeError CodeDescription
401INVALID_API_KEYAPI key is invalid or expired
401MISSING_AUTHENTICATIONNo authentication provided
401INVALID_TOKENAccess token is invalid or expired
403INSUFFICIENT_PERMISSIONSAPI key lacks required permissions
403SCOPE_INSUFFICIENTToken scope is insufficient

​
Error Response Format

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid",
    "details": "API key 'ak_1234567890' was not found"
  }
}

​
Testing Authentication

​
Test Your API Key

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.kaie.ai/v1/me

​
Test OAuth Flow

Use the OAuth playground to test your OAuth implementation:

OAuth Playground

Test OAuth authentication flows

​
Next Steps

Now that you understand authentication, explore the API endpoints:

Workflows API

Manage workflows programmatically

Analytics API

Access analytics data via API

Webhooks API

Set up webhook integrations

Triggers API

Manage workflow triggers