API Tokens

API tokens provide long-lived credentials for server-to-server integrations, scripts, and automation. Each token is scoped to a specific team.

Creating an API Token

1. Navigate to Team Settings

   Open the Catalyzed app and go to Settings (gear icon in the sidebar).

2. Select API Tokens

   This option is available to team Admins only.

3. Click Create Token

   Enter a descriptive name (e.g., “CI/CD Pipeline”, “Data Sync Script”).

4. Copy Your Token

   The token is displayed only once. Copy it immediately and store it securely.

Caution

API tokens are displayed only once at creation time. If you lose your token, you’ll need to create a new one.

Token Properties

Property	Description
Name	Human-readable identifier for the token
Team	The team this token can access
Role	Permission level (currently mirrors your team role)
Created	When the token was created
Last Used	When the token was last used for an API request

Using Your Token

Include the token in the Authorization header of every request:

Using an API token

cURL

export API_TOKEN="cat_tok_..."

curl https://api.catalyzed.ai/datasets \
  -H "Authorization: Bearer $API_TOKEN"

TypeScript

const API_TOKEN = process.env.CATALYZED_API_TOKEN;

const response = await fetch("https://api.catalyzed.ai/datasets", {
  headers: {
    Authorization: `Bearer ${API_TOKEN}`,
  },
});

Python

import os
import requests

api_token = os.environ["CATALYZED_API_TOKEN"]

response = requests.get(
    "https://api.catalyzed.ai/datasets",
    headers={"Authorization": f"Bearer {api_token}"}
)

Managing Tokens

List Your Tokens

View all tokens you’ve created in Settings > API Tokens. You can see:

• Token name
• Creation date
• Last used date
• Status (active/revoked)

Revoke a Token

To revoke a token:

1. Go to Settings > API Tokens
2. Find the token you want to revoke
3. Click the Revoke button

Revoked tokens immediately stop working. This action cannot be undone.

Revoking via API

You can also revoke tokens programmatically:

Revoke an API token

cURL

curl -X DELETE https://api.catalyzed.ai/api-tokens/_wfH8UWN56YW8mFgexoSx \
  -H "Authorization: Bearer $API_TOKEN"

TypeScript

await fetch("https://api.catalyzed.ai/api-tokens/_wfH8UWN56YW8mFgexoSx", {
  method: "DELETE",
  headers: {
    Authorization: `Bearer ${apiToken}`,
  },
});

Python

requests.delete(
    "https://api.catalyzed.ai/api-tokens/_wfH8UWN56YW8mFgexoSx",
    headers={"Authorization": f"Bearer {api_token}"}
)

Best Practices

Use Descriptive Names

Name tokens based on their purpose:

• production-etl-pipeline
• staging-data-sync
• github-actions-deploy

One Token Per Service

Create separate tokens for each integration. This allows you to:

• Track usage per service
• Revoke access for a single service without affecting others
• Identify which service made specific API calls

Store Tokens Securely

Never commit tokens to version control. Use:

• Environment variables
• Secrets managers (AWS Secrets Manager, HashiCorp Vault, etc.)
• CI/CD secrets (GitHub Secrets, GitLab CI Variables, etc.)

Rotate Tokens Periodically

For production systems, rotate tokens on a regular schedule:

1. Create a new token
2. Update your application to use the new token
3. Verify the new token works
4. Revoke the old token

Troubleshooting

Token Not Working

1. Check the token is correct - Ensure no extra whitespace or truncation
2. Verify the team - Tokens only work for resources in their team
3. Check token status - Ensure it hasn’t been revoked
4. Review permissions - Some operations require Admin role

Rate Limiting

API tokens share rate limits with the team. If you’re hitting rate limits:

• Review your request patterns
• Add caching where appropriate
• Contact support for limit increases

API Reference

See the API Tokens endpoints for the complete API documentation.