API Reference

Authentication

All API endpoints (except public tracking/unsubscribe URLs) require authentication via session cookie or Bearer token.

Login

bash
curl -X POST http://YOUR_SERVER/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin@company.com", "password": "yourpassword"}'

Response sets an auth_token HttpOnly cookie (7-day expiry). The token is NOT included in the JSON response for XSS protection.

Using the Token

Two methods:

Cookie (browser/curl)

bash
curl http://YOUR_SERVER/v1/outreach/campaigns \
  -H "Cookie: auth_token=YOUR_TOKEN"

Bearer Header (API clients)

bash
curl http://YOUR_SERVER/v1/outreach/campaigns \
  -H "Authorization: Bearer YOUR_TOKEN"

Check Current User

bash
curl http://YOUR_SERVER/v1/auth/me \
  -H "Cookie: auth_token=YOUR_TOKEN"

Logout

bash
curl -X POST http://YOUR_SERVER/v1/auth/logout \
  -H "Cookie: auth_token=YOUR_TOKEN"

Workspace Scoping

To scope API calls to a specific workspace, include the workspace ID or slug:

bash
# Via header
curl http://YOUR_SERVER/v1/outreach/campaigns \
  -H "X-Workspace-ID: my-workspace-slug" \
  -H "Cookie: auth_token=YOUR_TOKEN"

# Via query param
curl "http://YOUR_SERVER/v1/outreach/campaigns?workspace_id=my-workspace-slug" \
  -H "Cookie: auth_token=YOUR_TOKEN"
Rate limiting

Login attempts are rate-limited to 10 per IP per 10 minutes. After 10 failures, the IP is locked for 15 minutes.

Session Management

  • Sessions expire after 7 days
  • Max 50 sessions per user (oldest are pruned)
  • Expired sessions are cleaned up hourly
  • Changing password invalidates all other sessions