Authentication

The TeamDay API uses Personal Access Tokens (PAT) for authentication. All API requests must include a valid token in the Authorization header.

Getting Your Access Token

Step 1: Generate Token

Log in to your TeamDay account at cc.teamday.ai
Navigate to Settings → API Access
Click Generate New Token
Optionally set a custom expiration (7-365 days, default: 90 days)
Copy your token immediately - you won't be able to see it again!

Step 2: Store Securely

Your token will look like this:

td_AbCdEfGhIjKlMnOpQrStUvWxYz0123456789AbCdE

Token format:

Prefix: td_ (identifies TeamDay tokens)
Length: 43 alphanumeric characters after prefix
Encoding: Base64url (URL-safe)

Store in environment variables:

# Unix/Linux/macOS
export TEAMDAY_TOKEN="td_your-actual-token-here"

# Windows (PowerShell)
$env:TEAMDAY_TOKEN="td_your-actual-token-here"

# Or in .env file (for local development)
TEAMDAY_TOKEN=td_your-actual-token-here

Using Your Token

Include your token in the Authorization header with the Bearer scheme:

Authorization: Bearer td_your-actual-token-here

Example Requests

List agents:

curl https://cc.teamday.ai/api/v1/agents \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"

Create an agent:

curl -X POST https://cc.teamday.ai/api/v1/agents \
  -H "Authorization: Bearer $TEAMDAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Research Assistant",
    "role": "Research and analysis",
    "systemPrompt": "You are a helpful research assistant.",
    "visibility": "private"
  }'

Get execution details:

curl https://cc.teamday.ai/api/v1/executions/exec_123 \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"

Token Security Features

Encryption at Rest

Tokens are protected with enterprise-grade security:

Hashing: SHA-256 hash stored in database (irreversible)
Encryption: AES-256-GCM encryption for token metadata
No plain-text storage: Original token never stored after creation

Automatic Validation

Every API request validates:

Token format - Correct prefix and length
Hash lookup - Token exists in database
Expiration - Token not expired
Organization scope - User belongs to organization
Last used tracking - Updated on each request

Scoping

Each token is scoped to:

User: Token belongs to specific user (creator)
Organization: Inherits user's organization membership
Permissions: Uses user's role and permissions

Important: Tokens inherit the permissions of the user who created them. If a user's access is revoked, their tokens stop working immediately.

Token Management

View Active Tokens

See all your active tokens in Settings → API Access:

Token name (optional label)
Creation date
Last used timestamp
Expiration date
Permissions scope

Revoke Tokens

Immediately revoke a token:

Go to Settings → API Access
Find the token in your list
Click Revoke
Confirm deletion

When to revoke:

Token compromised or exposed
Team member leaves organization
Token no longer needed
Rotating credentials (security best practice)

Token Expiration

Default expiration: 90 days

Custom expiration:

Minimum: 7 days
Maximum: 365 days

What happens when expired:

API requests return 401 Unauthorized
Error message: "Token expired"
Token automatically cleaned up (soft delete)

Auto-renewal: Not supported. Generate a new token before expiration.

Error Responses

Missing Token

Request:

curl https://cc.teamday.ai/api/v1/agents

Response:

{
  "error": true,
  "statusCode": 401,
  "statusMessage": "Unauthorized",
  "message": "Authorization header required"
}

Invalid Token

Request:

curl https://cc.teamday.ai/api/v1/agents \
  -H "Authorization: Bearer invalid_token"

Response:

{
  "error": true,
  "statusCode": 401,
  "statusMessage": "Unauthorized",
  "message": "Invalid or expired token"
}

Expired Token

Request:

curl https://cc.teamday.ai/api/v1/agents \
  -H "Authorization: Bearer td_expired_token"

Response:

{
  "error": true,
  "statusCode": 401,
  "statusMessage": "Unauthorized",
  "message": "Token expired"
}

Security Best Practices

Do's ✅

Store tokens in environment variables - Never hardcode in source
Use separate tokens per integration - Easier to track and revoke
Set appropriate expiration dates - Shorter for high-risk environments
Rotate tokens regularly - Especially for production systems
Revoke immediately if compromised - Better safe than sorry
Use HTTPS only - Never send tokens over plain HTTP
Monitor token usage - Check "last used" timestamps regularly

Don'ts ❌

Never commit tokens to Git - Use .gitignore for .env files
Never share tokens - Each integration should have its own
Never log tokens - Redact from application logs
Never send in URL parameters - Use headers only
Never reuse across environments - Dev/staging/prod should have separate tokens
Never store in client-side code - Tokens are for server-side use only

Environment Variables Example

# .env (add to .gitignore!)
TEAMDAY_TOKEN=td_your-actual-token-here

# Usage in code
const token = process.env.TEAMDAY_TOKEN

const response = await fetch('https://cc.teamday.ai/api/v1/agents', {
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  }
})

Token Rotation Strategy

Recommended rotation schedule:

Development: 90 days (default)
Staging: 60 days
Production: 30 days
High-security: 7 days

How to rotate without downtime:

Generate new token (don't revoke old one yet)
Update applications to use new token
Deploy and verify new token works
Monitor for 24-48 hours (check old token usage)
Revoke old token once confirmed unused

Rate Limiting

Current status: No rate limits enforced

Best practices:

Implement exponential backoff for retries
Cache responses when appropriate
Use reasonable request rates (< 100 req/min recommended)

Future: Rate limits may be introduced. We'll provide advance notice and documentation.

OAuth (Coming Soon)

Planned features:

OAuth 2.0 support for third-party integrations
Scoped permissions (read-only, write, admin)
Organization-level API keys

Track OAuth progress →

Testing Your Token

Quick test:

# Should return list of agents (or empty array)
curl https://cc.teamday.ai/api/v1/agents \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"

# Success response (example)
[
  {
    "id": "agent_123",
    "name": "My Agent",
    "role": "Assistant",
    "createdAt": "2025-12-09T12:00:00Z"
  }
]

If you see 401 Unauthorized:

Verify token copied correctly (no extra spaces)
Check token not expired in Settings → API Access
Confirm user still has organization access
Try generating a fresh token

Need Help?

Token not working?

Check error reference for troubleshooting
Verify format: td_ + 43 characters
Confirm not expired in dashboard

Questions?

📧 Email: [email protected]
💬 Discord: Join community

Last Updated: December 9, 2025