# Integration Endpoints {#integration-endpoints}


API endpoints for managing third-party integrations.


## Integration Management {#integration-management}



### List Available Integration Types {#list-available-integration-types}


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


### List Active Integrations {#list-active-integrations}


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

**Response (200 OK):**

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


### Create Integration {#create-integration}


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

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


## GitHub Integration {#github-integration}



### Install GitHub App {#install-github-app}


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

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


### List GitHub Repositories {#list-github-repositories}


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


### Sync GitHub Issues {#sync-github-issues}


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

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


### GitHub Webhook {#github-webhook}


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


## Upwork Integration {#upwork-integration}



### Connect Upwork Account {#connect-upwork-account}


```http
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 {#sync-upwork-work-diary}


```http
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 {#hubstaff-integration}



### Connect HubStaff {#connect-hubstaff}


```http
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 {#sync-hubstaff-activities}


```http
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 {#activepieces-integration}



### Setup {#setup}


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

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


### Create/Update Connection {#createupdate-connection}


```http
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 {#list-connections}


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


### Get Connection {#get-connection}


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


### Delete Connection {#delete-connection}


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


### OAuth: Authorize (GET) {#oauth-authorize-get}


```http
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) {#oauth-authorize-post}


```http
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 {#oauth-token-exchange}


```http
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):**

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


## Integration Settings {#integration-settings}



### Get Integration Settings {#get-integration-settings}


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


### Update Integration Setting {#update-integration-setting}


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

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


## Entity Settings (Integration-Entity Mapping) {#entity-settings-integration-entity-mapping}



### Get Entity Settings {#get-entity-settings}


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


### Update Entity Setting {#update-entity-setting}


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

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


## Supported Integrations {#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 {#required-permissions}


| Endpoint                         | Permission         |
| -------------------------------- | ------------------ |
| `GET /api/integration`           | `INTEGRATION_VIEW` |
| `POST /api/integration`          | `INTEGRATION_EDIT` |
| `POST /api/integration/github/*` | `INTEGRATION_EDIT` |