Authentication#

CommFlow supports multiple authentication methods for different use cases. Choose the method that best fits your integration needs.

Authentication Methods#

API Keys#

API keys are the simplest way to authenticate server-side applications.

Creating API Keys#

1. Go to Settings > API
2. Click Create API Key
3. Enter a name (e.g., "CRM Integration")
4. Select scopes (permissions)
5. Click Create
6. Copy the key immediately (shown only once)

Using API Keys#

Include the key in the Authorization header:

GET /v1/conversations HTTP/1.1
Host: api.commflow.io
Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxx

Or with curl:

curl -X GET "https://api.commflow.io/v1/conversations" \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxx"

Key Types#

Test keys:

• Safe for development
• Don't affect live data
• Same API behavior

Key Management#

Viewing Keys:

• Go to Settings > API
• See all active keys
• View last used date

Revoking Keys:

1. Find the key to revoke
2. Click Revoke
3. Confirm revocation
4. Key immediately stops working

Rotating Keys:

1. Create a new key
2. Update your application
3. Verify it works
4. Revoke the old key

API Key Scopes#

Limit what each key can access:

Available Scopes#

Scope Best Practices#

1. Minimal permissions - Only request what you need
2. Separate keys - Different keys for different purposes
3. Read-only default - Start with read, add write as needed

Example Scoped Key#

For a reporting integration:

Scopes: conversations:read, contacts:read, tickets:read

This key can read data but cannot modify anything.

OAuth 2.0#

OAuth allows your app to act on behalf of users, with their permission.

When to Use OAuth#

• User-facing apps - Apps that users log into
• Marketplace apps - Third-party integrations
• Per-user permissions - Actions attributed to users

OAuth Flow Overview#

┌────────────┐                              ┌────────────┐
│            │  1. Authorization Request    │            │
│   Your     │ ───────────────────────────> │  CommFlow  │
│   App      │                              │            │
│            │  2. Authorization Code       │            │
│            │ <─────────────────────────── │            │
│            │                              └────────────┘
│            │  3. Exchange Code for Token  ┌────────────┐
│            │ ───────────────────────────> │  CommFlow  │
│            │                              │   API      │
│            │  4. Access Token             │            │
│            │ <─────────────────────────── │            │
│            │                              │            │
│            │  5. API Requests with Token  │            │
│            │ ───────────────────────────> │            │
└────────────┘                              └────────────┘

Setting Up OAuth#

1. Create OAuth App#

1. Go to Settings > API > OAuth Apps
2. Click Create App
3. Enter app details:
   • Name - Display name
   • Redirect URI - Your callback URL
   • Scopes - Required permissions
4. Save to get credentials

2. Get Credentials#

You'll receive:

• Client ID - Public identifier
• Client Secret - Keep this secret

Authorization Request#

Redirect users to authorize:

https://app.commflow.io/oauth/authorize
  ?client_id=YOUR_CLIENT_ID
  &redirect_uri=https://yourapp.com/callback
  &response_type=code
  &scope=conversations:read+contacts:read
  &state=random_state_string

Authorization Response#

After user approves, they're redirected to your callback:

https://yourapp.com/callback
  ?code=AUTH_CODE_HERE
  &state=random_state_string

Exchange Code for Token#

curl -X POST "https://api.commflow.io/oauth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "code": "AUTH_CODE_HERE",
    "redirect_uri": "https://yourapp.com/callback",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET"
  }'

Response:

{
  "access_token": "at_xxxxxxxxxxxxxx",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "rt_xxxxxxxxxxxxxx",
  "scope": "conversations:read contacts:read"
}

Using Access Tokens#

GET /v1/conversations HTTP/1.1
Host: api.commflow.io
Authorization: Bearer at_xxxxxxxxxxxxxx

Refreshing Tokens#

Access tokens expire. Use refresh tokens to get new ones:

curl -X POST "https://api.commflow.io/oauth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "refresh_token",
    "refresh_token": "rt_xxxxxxxxxxxxxx",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET"
  }'

Revoking Tokens#

curl -X POST "https://api.commflow.io/oauth/revoke" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "at_xxxxxxxxxxxxxx",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET"
  }'

Personal Access Tokens#

For individual developer use and testing.

Creating Personal Tokens#

1. Go to Settings > Account > Access Tokens
2. Click Generate Token
3. Name the token
4. Set expiration
5. Copy the token

Using Personal Tokens#

Same as API keys:

Authorization: Bearer pat_xxxxxxxxxxxxxx

Token Expiration#

Security Best Practices#

Protecting Credentials#

1. Never expose in client code - API keys should stay server-side
2. Use environment variables - Don't hardcode credentials
3. Don't commit to version control - Add to .gitignore
4. Encrypt at rest - Secure storage

Example: Environment Variables#

# .env file (not committed)
COMMFLOW_API_KEY=sk_live_xxxxxxxxxx

// app.js
const apiKey = process.env.COMMFLOW_API_KEY;

Key Rotation#

Rotate keys periodically:

1. Create new key with same scopes
2. Deploy update to use new key
3. Verify new key works
4. Revoke old key
5. Monitor for errors

Incident Response#

If a key is compromised:

1. Revoke immediately - Stop unauthorized access
2. Audit logs - Check for unauthorized activity
3. Create new key - For legitimate use
4. Investigate - How was it exposed?
5. Remediate - Fix the security gap

Authentication Errors#

Common Errors#

Error Response#

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "The API key provided is invalid."
  }
}

Testing Authentication#

Verify Your Key#

curl -X GET "https://api.commflow.io/v1/me" \
  -H "Authorization: Bearer YOUR_API_KEY"

Successful response:

{
  "id": "user_123",
  "email": "you@company.com",
  "name": "Your Name",
  "workspace": {
    "id": "ws_456",
    "name": "Your Workspace"
  }
}

Test vs Live Keys#

Use test keys during development:

# Development
COMMFLOW_API_KEY=sk_test_xxxxxxxxxx
 
# Production
COMMFLOW_API_KEY=sk_live_xxxxxxxxxx

Next Steps#

• API Overview - API basics
• Endpoints - Full endpoint reference