Authentication

CTWiseAPI uses API keys for authentication. All API requests must include a valid API key.

API Key Authentication

Include your API key in the x-api-key header:

curl -X GET "https://api.ctwise.ai/v1/catalog/sources" \
  -H "x-api-key: ctw_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Header Format

x-api-key: YOUR_API_KEY

API Key Format

API keys for CTWise use the ctw_ prefix:

Key Type	Prefix	Example
Production Keys	ctw_	ctw_3f8da4f058e8992f91c42ccfd00b31e3

API keys are 32-character hexadecimal strings prefixed with ctw_.

Creating API Keys

1. Sign in to your OrchestraPrime Dashboard
2. Navigate to Settings → API Keys
3. Click "Create New API Key"
4. Enter a descriptive name (e.g., "Production Backend")
5. Copy the key immediately - it won't be shown again

{
  "apiKey": "ctw_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "name": "Production Backend",
  "createdAt": "2025-01-15T10:30:00Z"
}

API Key Security

Best Practices

✅ Do:

• Store keys in environment variables or secrets managers
• Use different keys for different environments
• Rotate keys periodically
• Revoke unused keys

❌ Don't:

• Commit keys to version control
• Share keys in documentation or chat
• Include keys in client-side code
• Use the same key across all environments

Environment Variables

Linux/macOS:

export CTWISE_API_KEY="ctw_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Windows PowerShell:

$env:CTWISE_API_KEY = "ctw_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

In Code:

import os

api_key = os.environ.get("CTWISE_API_KEY")

Using AWS Secrets Manager

import boto3
import json

def get_api_key():
    client = boto3.client('secretsmanager')
    response = client.get_secret_value(SecretId='ctwise/api-key')
    return json.loads(response['SecretString'])['apiKey']

Key Rotation

To rotate an API key:

1. Create a new API key
2. Update your applications with the new key
3. Verify the new key works
4. Revoke the old key

warning

Revoking a key is immediate and irreversible. Ensure all applications are updated before revoking.

Error Responses

Invalid API Key

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The API key provided is invalid or has been revoked."
  }
}

HTTP Status: 401 Unauthorized

Missing API Key

{
  "message": "Unauthorized"
}

HTTP Status: 401 Unauthorized or 403 Forbidden

This error typically means the x-api-key header is missing or empty.

Expired Token

{
  "error": {
    "code": "EXPIRED_TOKEN",
    "message": "The authentication token has expired."
  }
}

HTTP Status: 401 Unauthorized

Rate Limiting by Key

Each API key has independent rate limiting:

Tier	Rate Limit
Free	2 requests/second
Starter	10 requests/second

See Rate Limits for details.

Troubleshooting

"Invalid API Key" Error

1. Check for typos or whitespace in the key
2. Verify the key hasn't been revoked
3. Ensure you're using the x-api-key header (not Authorization: Bearer)
4. Check if the key prefix is correct (ctw_)

Key Not Working After Rotation

1. Verify the new key was saved correctly
2. Clear any cached authentication
3. Check all services using the old key were updated
4. Review deployment configurations