Connections API

All connection endpoints require Executive access level.

Endpoints

`GET /api/admin/connections`

List all configured connections with status info (no tokens exposed).

Response:

{
  "connections": [
    {
      "provider": "xero",
      "org_name": "DotCollective Pty Ltd",
      "connected_by": "uuid",
      "connected_at": "2026-03-01T10:00:00",
      "token_expires_at": "2026-03-01T10:30:00"
    }
  ]
}

Xero (OAuth2)

`GET /api/admin/connections/xero/auth-url`

Generate a Xero OAuth2 authorization URL. Opens in a popup window.

Response: { "url": "https://login.xero.com/identity/connect/authorize?..." }

`POST /api/admin/connections/xero/callback`

Exchange the OAuth2 authorization code for tokens. Fetches tenant info, encrypts tokens, and stores in the connections table.

Body:

{
  "code": "authorization_code_from_xero"
}

`DELETE /api/admin/connections/xero`

Disconnect Xero. Removes the stored connection.

Productive (API Token)

`PUT /api/admin/connections/productive`

Save an encrypted Productive API token.

Body:

{
  "api_token": "string (required)"
}

`DELETE /api/admin/connections/productive`

Disconnect Productive.

Slack (Bot Token)

`PUT /api/admin/connections/slack`

Save an encrypted Slack bot token and target channel ID.

Body:

{
  "bot_token": "xoxb-... (required)",
  "channel_id": "C0123456789 (required)"
}

`DELETE /api/admin/connections/slack`

Disconnect Slack.

Google Calendar

`GET /api/admin/connections/google-calendar/status`

Check if Google Calendar integration is configured (via environment variables, not stored in DB).

Response: { "configured": true }

User Mappings

Map internal users to their external IDs in Xero and Productive.

`GET /api/admin/connections/user-mappings`

List all users with their external ID mappings.

Response:

{
  "mappings": [
    {
      "user_id": "uuid",
      "user_name": "Name",
      "user_email": "name@dotcollective.com.au",
      "xero_id": "xero-employee-id",
      "productive_id": "productive-person-id"
    }
  ]
}

`PUT /api/admin/connections/user-mappings/:userId`

Manually set external IDs for a user.

Body:

{
  "xero_id": "string (optional)",
  "productive_id": "string (optional)"
}

`POST /api/admin/connections/user-mappings/sync`

Auto-match users to external services by email address. Queries Xero employees and Productive people, matching by email.