API Authentication

Learn how to authenticate API requests with API keys.

Overview

All Contextium API requests require authentication using API keys.

API keys:

• Authenticate your identity
• Authorize access to workspace resources
• Track API usage
• Enable permission scoping

Creating API Keys

Requirements

• Professional plan or higher
• Workspace Owner, Admin, or Editor role

Create a Key

1. Navigate to Settings → API Keys
2. Click Create API Key
3. Configure the key:
   • Name - Descriptive name (e.g., "CI/CD Pipeline")
   • Permissions - Read, Write, or Admin
   • Expiration - Optional expiration date
4. Click Generate Key
5. Copy and securely store the key

Important: API keys are shown only once at creation. Store them securely immediately.

API Key Format

Keys follow the format:

doxhub_sk_live_abc123xyz789...

• doxhub - Service identifier
• sk - Secret key
• live - Environment (live or test)
• Followed by random characters

API Key Permissions

Read Permission

Read-only access to:

• View files and content
• View projects and folders
• View comments
• View version history
• Search content
• View team members (name and role only)

Cannot:

• Create, update, or delete files
• Modify workspace settings
• Manage team members

Write Permission

Read permission plus:

• Create, update, delete files
• Create, update, delete projects and folders
• Add comments
• Apply tags

Cannot:

• Manage team members
• Modify workspace settings
• Manage API keys

Admin Permission

Write permission plus:

• Manage team members (invite, remove, change roles)
• Configure integrations
• Manage webhooks
• View audit logs

Cannot:

• Access billing information
• Delete workspace
• Transfer ownership

Note: Only workspace Owners and Admins can create Admin-level API keys.

Using API Keys

Authentication Header

Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Example Requests

cURL:

curl https://api.contextium.io/files \
  -H "Authorization: Bearer doxhub_sk_live_abc123..."

JavaScript:

const response = await fetch('https://api.contextium.io/files', {
  headers: {
    'Authorization': 'Bearer doxhub_sk_live_abc123...',
    'Content-Type': 'application/json'
  }
});

Python:

import requests

headers = {
    'Authorization': 'Bearer doxhub_sk_live_abc123...',
    'Content-Type': 'application/json'
}

response = requests.get('https://api.contextium.io/files', headers=headers)

Environment Variables

Store keys in environment variables:

Bash:

export DOXHUB_API_KEY="doxhub_sk_live_abc123..."
curl https://api.contextium.io/files \
  -H "Authorization: Bearer $DOXHUB_API_KEY"

Node.js:

const apiKey = process.env.DOXHUB_API_KEY;
const response = await fetch('https://api.contextium.io/files', {
  headers: { 'Authorization': `Bearer ${apiKey}` }
});

Python:

import os

api_key = os.environ.get('DOXHUB_API_KEY')
headers = {'Authorization': f'Bearer {api_key}'}

Managing API Keys

View Active Keys

1. Navigate to Settings → API Keys
2. See all active keys with:
   • Key name
   • Permission level
   • Created date
   • Last used date
   • Expiration date (if set)

Rotate API Keys

Update keys regularly for security:

1. Create a new API key
2. Update applications to use new key
3. Verify new key works
4. Delete old key

Recommended: Rotate keys every 90 days.

Revoke API Keys

Delete keys immediately when:

• Key is compromised
• Integration no longer needed
• Employee leaves organization
• Testing is complete

To revoke:

1. Navigate to Settings → API Keys
2. Find the key to revoke
3. Click Delete
4. Confirm deletion

Revoked keys:

• Stop working immediately
• Return 401 Unauthorized errors
• Cannot be restored

Key Expiration

Set expiration dates on keys:

1. When creating key, set Expiration Date
2. Key automatically expires on date
3. API requests fail with 401 error after expiration

Useful for:

• Temporary integrations
• Testing and development
• Third-party access
• Time-limited projects

Receive email notifications:

• 7 days before expiration
• 1 day before expiration
• When key expires

Security Best Practices

Storage

Do:

• ✅ Store in environment variables
• ✅ Use secrets managers (AWS Secrets Manager, HashiCorp Vault)
• ✅ Use CI/CD secret storage (GitHub Secrets, GitLab CI/CD variables)
• ✅ Encrypt at rest

Don't:

• ❌ Commit to version control (git, SVN)
• ❌ Store in code files
• ❌ Share via email or chat
• ❌ Store in browser localStorage
• ❌ Log API keys

Access Control

• Use minimum required permissions (Read vs Write vs Admin)
• Create separate keys for different applications
• Rotate keys regularly (every 90 days)
• Set expiration dates when appropriate
• Revoke unused keys immediately

Monitoring

• Monitor API key usage in Settings → API Keys
• Check "Last Used" dates regularly
• Review audit logs for suspicious activity (Business plan+)
• Set up alerts for unusual API patterns

Key Compromise

If an API key is compromised:

1. Immediately revoke the key in Settings → API Keys
2. Review audit logs for unauthorized activity
3. Generate a new key with different permissions if needed
4. Update affected applications
5. Investigate how key was compromised
6. Contact support@contextium.io if sensitive data accessed

Rate Limiting

API keys are subject to rate limits based on plan:

Professional:

• 1,000 requests/hour
• 10,000 requests/day

Business:

• 5,000 requests/hour
• 50,000 requests/day

Enterprise:

• Custom limits

Rate limit applies per API key. Multiple keys = separate rate limits.

See Rate Limits for details.

Authentication Errors

401 Unauthorized

Causes:

• Invalid API key
• Expired API key
• Revoked API key
• Missing Authorization header

Solution:

• Verify API key is correct
• Check key hasn't expired or been revoked
• Ensure Authorization header is properly formatted

403 Forbidden

Causes:

• Insufficient permissions
• Attempting to access another workspace
• Resource doesn't exist or you don't have access

Solution:

• Check API key permissions (Read vs Write vs Admin)
• Verify you're accessing correct workspace
• Ensure resource exists and you have access

Example Error Response

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key",
    "details": {
      "reason": "The provided API key is invalid or has been revoked"
    }
  }
}

Testing API Keys

Test Endpoint

Verify your API key works:

curl https://api.contextium.io/auth/test \
  -H "Authorization: Bearer YOUR_API_KEY"

Success response:

{
  "authenticated": true,
  "workspace": {
    "id": "ws_abc123",
    "name": "My Workspace"
  },
  "key": {
    "name": "CI/CD Pipeline",
    "permissions": "write",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

Workspace Context

API keys are scoped to a workspace:

• Access only resources in that workspace
• Cannot access other workspaces
• Need separate keys for each workspace

To work with multiple workspaces:

1. Create API key in each workspace
2. Use appropriate key for each workspace
3. Or use user OAuth token (coming soon)

Coming Soon

Future authentication enhancements:

• OAuth 2.0 for user-based auth
• Temporary access tokens
• Service accounts
• IP whitelisting (Enterprise)
• SSO integration for API access

Next Steps

• View API reference
• Create your first API request
• Set up webhooks
• Monitor rate limits