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 keysCreate multiple keys with descriptive names for different integrations.
Per-key rate limitsSet custom rate limits (requests/minute) for each API key.
Usage analyticsTrack usage per key with endpoint-level visibility.
Secure hashingKeys 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
1Navigate to Settings → API Keys
2Click “Create New Key”
3Enter a descriptive name and optional rate limit
4Copy your key immediately — it won’t be shown again
Via API
Create API key · bash
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):
Response · json
{
"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:
API key request · bash
curl -X GET "https://app.cleartangle.com/api/tasks" \
-H "X-API-Key: ctak_xxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json"
Authentication priorityWhen 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.
SETTINGDEFAULTDESCRIPTION
rate_limit_per_minute60Max requests per minute per keyRate limit headers
Every API response includes rate limit information:
Response headers · http
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 85
X-RateLimit-Reset: 1706788800
Retry-After: 45
X-RateLimit-LimitMaximum requests per minute for this keyX-RateLimit-RemainingRemaining requests in current windowX-RateLimit-ResetUnix timestamp when the window resetsRetry-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 methodResponse status codesLast used timestamp and IP addressAggregated by minute windows
Usage API
Get usage analytics · bash
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 key · json
{
"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 authenticationYou 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 example · bash
# 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 variableYou can also set the API key via
CLEARTANGLE_API_KEY for non-interactive scripts.Key management
List keys
GET /api/api-keysReturns all your keys (prefix only, no secrets)Update key
PATCH /api/api-keys/:idUpdate name, rate limit, or expirationRevoke key
DELETE /api/api-keys/:idImmediately invalidates the keyKEY 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 repositoriesStore keys in environment variables or secure secret managersUse descriptive names to identify which integration uses each keySet appropriate rate limits based on expected usageRevoke unused or compromised keys immediatelyMonitor usage analytics for suspicious activityCreate separate keys for development and production
Error responses
401 UnauthorizedInvalid or missing API keySolution: Verify the key is correct and hasn’t been revoked.401 Key ExpiredAPI key has expiredSolution: Create a new key or update the expiration date.401 Key RevokedAPI key has been revokedSolution: Create a new API key and update your integration.429 Too Many RequestsRate limit exceeded for this keySolution: Wait for the window to reset or increase the rate limit.