Skip to main content
All API endpoints require authentication using both API key and secret headers. This guide explains how to generate, use, and manage your API credentials.

​
Required Headers

Every API request must include these headers:
​
X-API-KEY
string
required
Your API key (format: sk_<32 characters>)Example: sk_Abc123Def456Ghi789Jkl012Mno345Pqr678Stu901Vwx234YzThis is the public identifier for your API key.
​
X-API-SECRET
string
required
Your API secret (format: s3cr3t_<40 characters>)Example: s3cr3t_Xyz789Abc123Def456Ghi789Jkl012Mno345Pqr678Stu901Vwx234
The API secret is shown only once when you generate your API key. Store it securely - it cannot be retrieved later!
Organization ID: The organization ID is automatically extracted from your API key and secret during authentication. You do not need to include an orgId header in your requests.

​
Generating API Keys

API keys can only be generated through the organization portal (requires JWT authentication): 
POST /api/organizations/{organizationId}/api-keys
Authorization: Bearer <JWT_TOKEN>

{
  "message": "API key generated successfully",
  "status": "success",
  "error": null,
  "data": {
    "api_key_id": "apikey_abc123...",
    "api_key": "sk_Abc123Def456Ghi789Jkl012Mno345Pqr678Stu901Vwx234Yz",
    "api_secret": "s3cr3t_Xyz789Abc123Def456Ghi789Jkl012Mno345Pqr678Stu901Vwx234",
    "organization_id": "org_1234567890",
    "status": "ACTIVE",
    "created_at": "2024-01-15T10:30:00Z",
    "warning": "⚠️ Store both API key and secret securely. The secret cannot be retrieved later!"
  }
}

​
Using API Keys

Include both headers in every API request: 
curl -X POST "https://api.zudu.ai/api/agents/agent_123/duplicate" \
  -H "X-API-KEY: sk_Abc123Def456Ghi789Jkl012Mno345Pqr678Stu901Vwx234Yz" \
  -H "X-API-SECRET: s3cr3t_Xyz789Abc123Def456Ghi789Jkl012Mno345Pqr678Stu901Vwx234" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_name": "New Agent Copy"
  }'

​
Security Best Practices

Store Securely

Never commit API keys or secrets to version control. Use environment variables or secret management services (AWS Secrets Manager, HashiCorp Vault).

Rotate Regularly

Regenerate your API keys every 90 days or if you suspect they’ve been compromised.

Use Different Keys

Use separate API keys for different environments (development, staging, production).

Monitor Usage

Regularly check your API key usage and revoke unused or compromised keys immediately.

​
Key Management

​
List API Keys

View all API keys for your organization (secrets are not shown): 
GET /api/organizations/{organizationId}/api-keys
Authorization: Bearer <JWT_TOKEN>

{
  "message": "API keys retrieved successfully",
  "status": "success",
  "data": {
    "api_keys": [
      {
        "api_key_id": "apikey_abc123...",
        "api_key": "sk_Abc123Def456...",
        "status": "ACTIVE",
        "created_at": "2024-01-15T10:30:00Z",
        "last_used_at": "2024-01-20T14:22:00Z",
        "last_used_ip": "192.168.1.100"
      }
    ],
    "count": 1,
    "note": "API secrets are not shown - they cannot be retrieved after generation"
  }
}

​
Regenerate API Key

If you lose your secret or suspect it’s compromised, regenerate the key (revokes old, creates new): 
POST /api/organizations/{organizationId}/api-keys/{apiKeyId}/regenerate
Authorization: Bearer <JWT_TOKEN>

​
Revoke API Key

Immediately revoke a compromised or unused API key: 
DELETE /api/organizations/{organizationId}/api-keys/{apiKeyId}
Authorization: Bearer <JWT_TOKEN>

​
Error Responses

​
error
string
Unauthorized - Missing or invalid API key/secret
{
  "message": "Authentication Failed",
  "error": "Invalid API secret"
}
​
error
string
Forbidden - API key is revoked or inactive
{
  "message": "Authentication Failed",
  "error": "API key is not active"
}

​
Key Format Details

  • API Key: Always starts with sk_ followed by 32 URL-safe characters
  • API Secret: Always starts with s3cr3t_ followed by 40 URL-safe characters
  • Both are case-sensitive and must match exactly

​
Rate Limits

API keys are subject to rate limiting based on your organization’s subscription plan. Check your organization settings for specific limits.