API Keys

Secure authentication for external integrations

API Keys provide a secure way to authenticate external systems with your Clear Tangle account. Each key can have its own rate limits and usage tracking, making it easy to manage multiple integrations including the MCP server for AI assistants.

Key Prefix Format

All API keys use the ctak_ prefix (Clear Tangle API Key) followed by a unique identifier.

Key Features

Named Keys

Create multiple keys with descriptive names for different integrations

Per-Key Rate Limits

Set custom rate limits (requests/minute) for each API key

Usage Analytics

Track usage per key with endpoint-level visibility

Secure Hashing

Keys are stored as hashes - only shown once at creation

Creating API Keys

Create API keys from the Settings > API Keys page in the app, or via the API:

Via Settings UI

1.Navigate to Settings > API Keys
2.Click "Create New Key"
3.Enter a descriptive name and optional rate limit
4.Copy your key immediately - it won't be shown again!

Via API

Create API Keybash

curl -X POST "https://app.cleartangle.com/api/api-keys" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Integration",
    "rate_limit_per_minute": 120
  }'

Response (key shown only once):

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "key": "ctak_xxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "key_prefix": "ctak_xxxx",
  "name": "Production Integration",
  "rate_limit_per_minute": 120,
  "created_at": "2026-02-01T10:00:00Z"
}

Save Your Key

The full API key is only displayed once when created. Store it securely - you cannot retrieve it later. If lost, revoke the key and create a new one.

Using API Keys

Include your API key in the X-API-Key header:

curl -X GET "https://app.cleartangle.com/api/tasks" \
  -H "X-API-Key: ctak_xxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json"

Authentication Priority

When both X-API-Key and Authorization: Bearer headers are present, the API key takes precedence. This ensures usage is tracked per key.

Rate Limiting

Each API key can have its own rate limit. The default is 60 requests per minute if not specified.

Setting	Default	Description
`rate_limit_per_minute`	60	Max requests per minute per key

Rate Limit Headers

Every API response includes rate limit information:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 85
X-RateLimit-Reset: 1706788800
Retry-After: 45

X-RateLimit-LimitMaximum requests per minute for this key

X-RateLimit-RemainingRemaining requests in current window

X-RateLimit-ResetUnix timestamp when the window resets

Retry-AfterSeconds to wait (only on 429 responses)

Usage Tracking

Monitor API key usage with detailed analytics including request counts by endpoint, method, and status code.

What's Tracked

Request count by endpoint and method
Response status codes
Last used timestamp and IP address
Aggregated by minute windows

Usage API

Get Usage Analyticsbash

curl -X GET "https://app.cleartangle.com/api/api-keys/KEY_ID/usage?from=2026-01-01&to=2026-02-01&groupBy=day" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Query parameters: from, to (ISO dates), and groupBy (day, hour).

MCP Server Integration

API keys are the recommended authentication method for the Clear Tangle MCP Server. They persist without expiration and don't require browser-based login.

Configuration

Add your API key to the MCP configuration:

MCP Config with API Keyjson

{
  "mcpServers": {
    "clear-tangle": {
      "command": "npx",
      "args": ["-y", "clear-tangle-mcp"],
      "env": {
        "CLEARTANGLE_API_KEY": "ctak_xxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "BACKEND_URL": "https://app.cleartangle.com/api"
      }
    }
  }
}

Alternative: Runtime Authentication

You can also set the API key at runtime by telling your AI assistant: "Set my Clear Tangle API key to ctak_xxxx_..."

Clear Tangle CLI

API keys are the recommended authentication method for the Clear Tangle CLI. Use them for secure automation and scripting.

CLI auth examplebash

# Set API key for Clear Tangle CLI
ct auth set-key ctak_xxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Verify authentication
ct auth status

# Make a request
ct tasks list

Environment Variable

You can also set the API key via CLEARTANGLE_API_KEYfor non-interactive scripts.

Key Management

List Keys

GET /api/api-keys - Returns all your keys (prefix only, no secrets)

Update Key

PATCH /api/api-keys/:id - Update name, rate limit, or expiration

Revoke Key

DELETE /api/api-keys/:id - Immediately invalidates the key

Key Rotation

For security best practices, rotate API keys periodically. Create a new key, update your integrations, then revoke the old key.

Security Best Practices

Never expose API keys in client-side code or public repositories

Store keys in environment variables or secure secret managers

Use descriptive names to identify which integration uses each key

Set appropriate rate limits based on expected usage

Revoke unused or compromised keys immediately

Monitor usage analytics for suspicious activity

Create separate keys for development and production

Error Responses

401 Unauthorized

Invalid or missing API key

Solution: Verify the key is correct and hasn't been revoked

401 Key Expired

API key has expired

Solution: Create a new key or update the expiration date

401 Key Revoked

API key has been revoked

Solution: Create a new API key and update your integration

429 Too Many Requests

Rate limit exceeded for this key

Solution: Wait for the window to reset or increase the rate limit