Authentication

Secure your API requests

Clear Tangle API supports two authentication methods: API Keys for server-to-server communication and OAuth 2.0 for user-authorized applications. Choose the method that best fits your use case.

Authentication Methods

API Keys

Best for server-side applications, scripts, and automated workflows.

  • Simple to implement
  • No user interaction needed
  • Full account access

OAuth 2.0

Best for apps that act on behalf of users.

  • User-authorized access
  • Granular scopes
  • Refresh tokens

API Keys

API keys provide a straightforward way to authenticate requests with per-key rate limits and usage tracking. Generate keys from your Settings > API Keys.

Key Format

ctak_*Clear Tangle API Keys

All API keys use the ctak_ prefix. Each key can have custom rate limits and shows detailed usage analytics.

Usage

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

curl -X GET "https://app.cleartangle.com/api/captures" \
  -H "X-API-Key: ctak_xxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json"
Learn more about API keys

OAuth 2.0

OAuth 2.0 allows your application to access Clear Tangle on behalf of users. Implement the Authorization Code flow for web applications.

Available Scopes

ScopeDescription
readRead access to captures, tasks, and pages
writeCreate and update captures, tasks, and pages
deleteDelete captures, tasks, and pages
chatAccess AI chat functionality
offline_accessRequest refresh tokens

Authorization Flow

// Step 1: Redirect user to authorization URL
const authUrl = "https://auth.cleartangle.com/oauth/authorize?" +
  "client_id=YOUR_CLIENT_ID&" +
  "redirect_uri=YOUR_REDIRECT_URI&" +
  "response_type=code&" +
  "scope=read write";

// Step 2: Exchange authorization code for access token
const response = await fetch("https://auth.cleartangle.com/oauth/token", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    grant_type: "authorization_code",
    client_id: "YOUR_CLIENT_ID",
    client_secret: "YOUR_CLIENT_SECRET",
    code: "AUTHORIZATION_CODE",
    redirect_uri: "YOUR_REDIRECT_URI"
  })
});

const { access_token, refresh_token } = await response.json();

Refresh Tokens

Access tokens expire after 1 hour. Use refresh tokens to obtain new access tokens without requiring user interaction:

const response = await fetch("https://auth.cleartangle.com/oauth/token", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    grant_type: "refresh_token",
    client_id: "YOUR_CLIENT_ID",
    client_secret: "YOUR_CLIENT_SECRET",
    refresh_token: "YOUR_REFRESH_TOKEN"
  })
});

Security Best Practices

Keep Credentials Secret

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

Store API keys in environment variables
Use HTTPS for all API requests
Rotate API keys periodically
Use minimal required scopes for OAuth
Implement proper error handling for auth failures
Monitor API usage for suspicious activity

Common Errors

401 Unauthorized

Invalid API key or expired token

Solution: Verify your API key is correct and hasn't been revoked. For OAuth, refresh the access token.

403 Forbidden

Insufficient scope

Solution: Request additional scopes during OAuth authorization.

401 Token Expired

Access token has expired

Solution: Use the refresh token to obtain a new access token.

Next Steps

API Keys GuideCaptures APITasks API