API Keys

API Keys

API keys are the simplest way to authenticate with the Coline API. They're ideal for:

• Server-to-server integrations
• Background scripts and automation
• Internal tools
• Testing and development

Each API key is scoped to a single workspace and has all the permissions of the user who created it.

Creating an API Key

1. Go to coline.app/developers/console
2. Select your workspace
3. Navigate to API Keys in the sidebar
4. Click Create API Key
5. Give it a descriptive name (e.g., "CI/CD Pipeline", "Data Sync Script")
6. Select the scopes you need (e.g., workspace.read, apps.read, files.read)
7. Click Create
8. Copy the secret immediately — it won't be shown again

The secret starts with col_ws_ followed by a unique identifier. Store it securely in your environment variables or secret manager.

Key Format

API keys start with col_ws_ followed by a unique identifier:

col_ws_a1b2c3d4e5f6...

Using API Keys

Include the key in the Authorization header:

curl https://api.coline.app/v1/workspaces/acme/drives \
  -H "Authorization: Bearer col_ws_xxx"

With the SDK:

import { ColineApiClient } from '@colineapp/sdk'

const client = new ColineApiClient({
  baseUrl: 'https://api.coline.app',
  apiKey: process.env.COLINE_API_KEY
})

Permissions

API keys inherit the permissions of the creating user:

• Can access all drives the user can access
• Can read/write files based on user permissions
• Can post to channels the user is a member of
• Can manage calendar events the user owns or is invited to

If you need different permission levels, create separate API keys from accounts with those permissions.

Security Best Practices

Storage

• Never commit API keys to version control
• Store keys in environment variables
• Use secret management systems (AWS Secrets Manager, HashiCorp Vault)
• Rotate keys regularly

// Good
const client = new ColineApiClient({
  baseUrl: 'https://api.coline.app',
  apiKey: process.env.COLINE_API_KEY
})

// Bad
const client = new ColineApiClient({
  baseUrl: 'https://api.coline.app',
  apiKey: 'col_ws_abc123...' // Never do this
})

Network Security

• Only use API keys over HTTPS
• Whitelist IP addresses if possible
• Monitor for unusual API activity

Key Rotation

Rotate keys periodically:

1. Generate a new key
2. Update your application to use the new key
3. Test thoroughly
4. Revoke the old key

Revoking Keys

If a key is compromised or no longer needed:

1. Go to coline.app/developers/console
2. Select your workspace
3. Navigate to API Keys in the sidebar
4. Find the key in the list
5. Click Revoke
6. The key is immediately invalidated

Revoked keys return 401 Unauthorized on all requests.

Rate Limits

API keys have the following rate limits:

• Read operations (GET, HEAD): 300 requests per minute
• Write operations (POST, PUT, PATCH, DELETE): 60 requests per minute

Limits reset every 60 seconds. Rate limit headers are included in all responses:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 299
X-RateLimit-Reset: 1712345678

Webhooks and API Keys

When using webhooks with API key authentication:

• Webhook signatures are verified using a separate secret
• The webhook secret is different from the API key
• Store both securely

Troubleshooting

401 Unauthorized

• Key is revoked or invalid
• Key is scoped to a different workspace
• Authorization header format is wrong (must be "Bearer {token}")

403 Forbidden

• Key is valid but lacks permission for the resource
• User who created key lost access to the workspace
• Resource is explicitly restricted

429 Too Many Requests

• Rate limit exceeded
• Implement exponential backoff
• Check Retry-After header

When to Use OAuth Instead

Use OAuth instead of API keys when:

• Building an app for multiple users/workspaces
• Users need to grant limited permissions
• App needs to act on behalf of users
• You need refresh tokens for long-term access

See OAuth 2.0 for third-party app authentication.

Next Steps

• OAuth 2.0 — Authenticate on behalf of users
• Scopes — Available permission scopes
• Security Best Practices — Keep your integration secure