Integration Endpoints

API endpoints for managing third-party integrations.

Integration Management

List Available Integration Types

GET /api/integration-type
Authorization: Bearer {token}

List Active Integrations

GET /api/integration?where[organizationId]={org-id}
Authorization: Bearer {token}

Response (200 OK):

{
  "items": [
    {
      "id": "...",
      "name": "GitHub",
      "isActive": true,
      "entitySettings": [...],
      "organizationId": "...",
      "integration": {
        "name": "GitHub",
        "imgSrc": "github.svg"
      }
    }
  ],
  "total": 3
}

Create Integration

POST /api/integration
Authorization: Bearer {token}
Content-Type: application/json

{
  "name": "GitHub",
  "integrationId": "github-type-uuid",
  "organizationId": "org-uuid"
}

GitHub Integration

Install GitHub App

POST /api/integration/github/install
Authorization: Bearer {token}
Content-Type: application/json

{
  "installation_id": "12345",
  "organizationId": "org-uuid"
}

List GitHub Repositories

GET /api/integration/github/repositories?integrationId={integration-id}
Authorization: Bearer {token}

Sync GitHub Issues

POST /api/integration/github/sync-issues
Authorization: Bearer {token}
Content-Type: application/json

{
  "integrationId": "integration-uuid",
  "repository": "owner/repo-name"
}

GitHub Webhook

POST /api/integration/github/webhook
X-GitHub-Event: {event-type}
X-Hub-Signature-256: {signature}

Upwork Integration

Connect Upwork Account

POST /api/integrations/upwork/token
Authorization: Bearer {token}
Content-Type: application/json

{
  "accessToken": "upwork-access-token",
  "accessTokenSecret": "upwork-token-secret",
  "organizationId": "org-uuid"
}

Sync Upwork Work Diary

POST /api/integrations/upwork/sync-contracts
Authorization: Bearer {token}
Content-Type: application/json

{
  "integrationId": "integration-uuid",
  "dateRange": {
    "start": "2024-01-01",
    "end": "2024-01-31"
  }
}

HubStaff Integration

Connect HubStaff

POST /api/integrations/hubstaff/token
Authorization: Bearer {token}
Content-Type: application/json

{
  "accessToken": "hubstaff-access-token",
  "refreshToken": "hubstaff-refresh-token",
  "organizationId": "org-uuid"
}

Sync HubStaff Activities

POST /api/integrations/hubstaff/sync-activities
Authorization: Bearer {token}
Content-Type: application/json

{
  "integrationId": "integration-uuid",
  "dateRange": {
    "start": "2024-01-01",
    "end": "2024-01-31"
  }
}

Activepieces Integration

Setup

POST /api/integration/activepieces/setup
Authorization: Bearer {token}
Content-Type: application/json

{
  "apiKey": "your-activepieces-api-key"
}

Create/Update Connection

POST /api/integration/activepieces/connection
Authorization: Bearer {token}
Content-Type: application/json

{
  "pieceName": "piece-name",
  "displayName": "My Connection",
  "type": "SECRET_TEXT",
  "value": { "secret": "..." }
}

List Connections

GET /api/integration/activepieces/connections/{integrationId}
Authorization: Bearer {token}

Get Connection

GET /api/integration/activepieces/connection/{integrationId}
Authorization: Bearer {token}

Delete Connection

DELETE /api/integration/activepieces/connection/{integrationId}
Authorization: Bearer {token}

OAuth: Authorize (GET)

GET /api/integration/activepieces/authorize?client_id={id}&redirect_uri={uri}&scope={scope}&state={state}

Redirects the user to the Gauzy consent screen at /pages/auth/oauth/authorize.

OAuth: Authorize (POST)

POST /api/integration/activepieces/authorize
Authorization: Bearer {token}

Called by the Gauzy frontend after the user clicks "Authorize". Returns an HMAC-signed, single-use authorization code and redirects back to Activepieces.

OAuth: Token Exchange

POST /api/integration/activepieces/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code={code}&client_id={id}&client_secret={secret}&redirect_uri={uri}

Response (200 OK):

{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 86400
}

Integration Settings

Get Integration Settings

GET /api/integration-setting?where[integrationId]={integration-id}
Authorization: Bearer {token}

Update Integration Setting

PUT /api/integration-setting/{id}
Authorization: Bearer {token}
Content-Type: application/json

{
  "settingsName": "sync_frequency",
  "settingsValue": "30"
}

Entity Settings (Integration-Entity Mapping)

Get Entity Settings

GET /api/integration-entity-setting?where[integrationId]={integration-id}
Authorization: Bearer {token}

Update Entity Setting

PUT /api/integration-entity-setting/{id}
Authorization: Bearer {token}
Content-Type: application/json

{
  "entity": "Project",
  "sync": true
}

Supported Integrations

Integration	Status	Sync Direction
GitHub	✅ Active	Bi-directional
Upwork	✅ Active	Import
HubStaff	✅ Active	Import
Jira	✅ Active	Bi-directional
Zapier	✅ Active	Webhook-based
Make.com	✅ Active	Webhook-based
ActivePieces	✅ Active	Bi-directional

Required Permissions

Endpoint	Permission
GET /api/integration	INTEGRATION_VIEW
POST /api/integration	INTEGRATION_EDIT
POST /api/integration/github/*	INTEGRATION_EDIT