Clear Tangle
Sign in Try for free
Docs/API Reference/Authentication

Authentication.

Secure your API requests.

The 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 keysBest for server-side applications, scripts, and automated workflows.
Simple to implementNo user interaction neededFull account access
OAuth 2.0Best for apps that act on behalf of users.
User-authorized accessGranular scopesRefresh tokens

API keys

API keys provide a straightforward way to authenticate requests with per-key rate limits and usage tracking. Generate keys from 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:

API key request · bash
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

Authorization code flow · javascript
// Step 1: Redirect user to authorization URL
const sc-camel-auth-url = "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:

Refresh an access token · javascript
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 variablesUse HTTPS for all API requestsRotate API keys periodicallyUse minimal required scopes for OAuthImplement proper error handling for auth failuresMonitor API usage for suspicious activity

Common errors

401 UnauthorizedInvalid API key or expired tokenSolution: Verify your API key is correct and hasn’t been revoked. For OAuth, refresh the access token.
403 ForbiddenInsufficient scopeSolution: Request additional scopes during OAuth authorization.
401 Token ExpiredAccess token has expiredSolution: Use the refresh token to obtain a new access token.

Next steps

API Authentication | Clear Tangle Documentation
Clear Tangle
Sign in Try for free
Docs/API Reference/Authentication

Authentication.

Secure your API requests.

The 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 keysBest for server-side applications, scripts, and automated workflows.
Simple to implement
No user interaction needed
Full account access
OAuth 2.0Best 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 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:

API key request · bash
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

Authorization code flow · javascript
// 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:

Refresh an access token · javascript
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 UnauthorizedInvalid API key or expired tokenSolution: Verify your API key is correct and hasn’t been revoked. For OAuth, refresh the access token.
403 ForbiddenInsufficient scopeSolution: Request additional scopes during OAuth authorization.
401 Token ExpiredAccess token has expiredSolution: Use the refresh token to obtain a new access token.

Next steps