API Endpoints¶
All routes are served via AWS API Gateway at the /api prefix. Unless noted, all endpoints require Cognito User Pool authorization via JWT Bearer token.
Task Routes¶
Lambda: task-sync
| Method | Path | Auth | Description |
|---|---|---|---|
| GET | /api/tasks |
Cognito | List tasks. Query: lastSyncTimestamp, userId |
| POST | /api/tasks |
Cognito (internal) | Create a new task |
| PUT | /api/tasks/{id} |
Cognito (internal) | Update an existing task |
| GET | /api/tasks/internal-users |
Cognito (internal) | List internal (non-customer) Cognito users |
| GET | /api/sync |
Cognito (internal) | Bi-directional sync for desktop clients |
Timer Routes¶
Lambda: time-entry-sync
| Method | Path | Auth | Description |
|---|---|---|---|
| POST | /api/tasks/{id}/start |
Cognito | Start timer for a task |
| POST | /api/tasks/{id}/stop |
Cognito | Stop timer, creates/updates associated TimeBill |
Time Entry Routes¶
Lambda: time-entry-sync
| Method | Path | Auth | Description |
|---|---|---|---|
| GET | /api/time-entries |
Cognito | List entries. Query: taskId, userId, startDate, endDate, customer/customerId, enrich |
| PATCH | /api/time-entries/{id} |
Cognito | Edit entry (startTime, endTime, duration). Recalculates time bills |
| POST | /api/time-entries/{id}/notes |
Cognito | Update notes on entry |
Time Bill Routes¶
Lambda: time-entry-sync
| Method | Path | Auth | Description |
|---|---|---|---|
| GET | /api/time-bills |
Cognito | List bills. Query: startDate, endDate, customer/customerId, userId, enrich |
| PATCH | /api/time-bills/{id} |
Cognito | Update bill (memo by owner, status/rejectionNote by admin). Triggers Xero sync on approval |
| POST | /api/time-bills/recompute |
Cognito (admin) | Backfill time bills from all time entries |
| POST | /api/time-bills/approve-all |
Cognito (admin) | Batch approve multiple bills |
Customer Routes¶
Lambda: customer-sync
| Method | Path | Auth | Description |
|---|---|---|---|
| GET | /api/customers |
Cognito | List customers. Query: lastSyncTimestamp |
| POST | /api/customers |
Cognito | Create customer (auto-creates "General Support" pillar) |
| PUT | /api/customers/{id} |
Cognito | Update customer |
| DELETE | /api/customers/{id} |
Cognito | Delete customer |
| POST | /api/leads |
None (public) | Accept lead from marketing site contact form |
Customer User Routes¶
Lambda: customer-sync
| Method | Path | Auth | Description |
|---|---|---|---|
| GET | /api/customers/{id}/users |
Cognito | List users for a customer |
| POST | /api/customers/{id}/users/invite |
Cognito | Invite user (creates Cognito user, sends email) |
| POST | /api/customers/{id}/users/resend-invite |
Cognito | Resend invitation email |
| DELETE | /api/customers/{id}/users/{userId} |
Cognito | Remove customer user from Cognito and DynamoDB |
Pillar Routes¶
Lambda: customer-sync
| Method | Path | Auth | Description |
|---|---|---|---|
| GET | /api/customers/{id}/pillars |
Cognito | List pillars for customer |
| POST | /api/customers/{id}/pillars |
Cognito | Create pillar |
| PUT | /api/customers/{id}/pillars/{pillarId} |
Cognito | Update pillar. Sends email to internal users if inactivated |
| DELETE | /api/customers/{id}/pillars/{pillarId} |
Cognito | Delete pillar (blocked if referenced by time bills) |
Customer Focus Routes¶
Lambda: customer-sync
| Method | Path | Auth | Description |
|---|---|---|---|
| PUT | /api/customers/{id}/focus |
Cognito (internal) | Set focus on a customer for real-time UI |
| DELETE | /api/customers/{id}/focus |
Cognito (internal) | Clear customer focus |
Active Timer Routes¶
Lambda: active-timer-sync
| Method | Path | Auth | Description |
|---|---|---|---|
| GET | /api/active-timers/{id} |
Cognito | Get active timer for user |
| PUT | /api/active-timers/{id} |
Cognito | Create or update active timer |
| DELETE | /api/active-timers/{id} |
Cognito | Delete active timer |
Xero Integration Routes¶
Lambda: xero-sync
| Method | Path | Auth | Description |
|---|---|---|---|
| GET | /api/xero/auth-url |
Cognito | Get Xero OAuth authorization URL |
| POST | /api/xero/connect |
Cognito | Exchange authorization code for tokens |
| GET | /api/xero/status |
Cognito | Check Xero connection status |
| DELETE | /api/xero/disconnect |
Cognito | Disconnect from Xero (clear tokens) |
| GET | /api/xero/projects/{projectId}/tasks |
Cognito | List tasks for a Xero project |
Slack Integration Routes¶
Lambda: slack-integration
| Method | Path | Auth | Description |
|---|---|---|---|
| POST | /api/slack/events |
Slack signature | Slash commands (/task) and event subscriptions |
| POST | /api/slack/interactivity |
Slack signature | Modal submissions and message action callbacks |
| GET | /api/slack/channel-mappings |
Cognito | List channel-to-customer/pillar mappings |
| POST | /api/slack/channel-mappings |
Cognito | Create channel mapping |
| PUT | /api/slack/channel-mappings/{id} |
Cognito | Update channel mapping |
| DELETE | /api/slack/channel-mappings/{id} |
Cognito | Delete channel mapping |
CORS¶
All routes include OPTIONS preflight methods with mock integration responses. CORS headers are configured on:
- All successful Lambda responses
- API Gateway 4xx and 5xx error responses (via Gateway Response configuration)
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Content-Type,Authorization
Access-Control-Allow-Methods: OPTIONS,GET,POST,PUT,PATCH,DELETE
Auth Types¶
| Type | Description |
|---|---|
| Cognito | JWT Bearer token from Cognito User Pool. All authenticated endpoints. |
| Cognito (internal) | Cognito auth + custom:userRole must start with internal_ (or be unset for legacy admins) |
| Cognito (admin) | Cognito auth + admin-level role check |
| Slack signature | HMAC SHA256 verification using SLACK_SIGNING_SECRET. No Cognito. |
| None (public) | No authentication required |