Core CRUD

Basic integration creation, retrieval, update, and deletion operations.

GET /api/integrations

List all non-embedded integrations.

Authentication: Required

Query Parameters:

Parameter	Type	Default	Description
q	string	-	Full-text search query (searches name, description)
supportsUpload	boolean	-	Filter by upload support capability

Response:

The response is a paginated HAL collection. Integration items are returned under _embedded["inf:integration"].

{
  "_links": {
    "self": { "href": "/api/integrations" }
  },
  "_embedded": {
    "inf:integration": [
      {
        "_links": {
          "self": { "href": "/api/integrations/a1b2c3d4-..." }
        },
        "id": "a1b2c3d4-...",
        "name": "Google Drive - Engineering",
        "slug": "google-drive-engineering",
        "type": "google-drive",
        "category": "storage",
        "description": "Integration with Google Drive for document sync",
        "mode": "per-user",
        "authType": "oauth2",
        "embedded": false,
        "scope": "https://www.googleapis.com/auth/drive.readonly",
        "authUri": "https://accounts.google.com/o/oauth2/v2/auth",
        "tokenUri": "https://oauth2.googleapis.com/token",
        "apiBaseUri": "https://www.googleapis.com/drive/v3",
        "createdAt": "2024-01-15T09:00:00.000Z",
        "updatedAt": "2024-02-08T14:00:00.000Z"
      }
    ]
  },
  "start": 0,
  "count": 1,
  "total": 8
}

Embedded Integrations

This endpoint excludes embedded integrations (created automatically for libraries). Embedded integrations are accessed via library endpoints.

---

GET /api/integrations-list

Get a flat list of all non-embedded integrations with tags and sharing data. Returns a plain array (not HAL-wrapped). Used by integration galleries and pickers.

Authentication: Required

Response:

[
  {
    "id": "a1b2c3d4-...",
    "name": "Google Drive - Engineering",
    "slug": "google-drive-engineering",
    "type": "google-drive",
    "category": "storage",
    "description": "Integration with Google Drive for document sync",
    "mode": "per-user",
    "authType": "oauth2",
    "ownerId": "admin",
    "embedded": false,
    "shared": true,
    "tags": ["tag-uuid-1", "tag-uuid-2"],
    "sharing": [
      {
        "principalId": "marketing",
        "accessLevel": 1
      }
    ]
  }
]

Key Fields:

Field	Description
tags	Array of tag IDs associated with this integration
sharing	Array of share objects with principalId and accessLevel

Permissions Required: None (returns only integrations user can read)

ETag Support: This endpoint supports ETags for efficient caching.

---

GET /api/integrations/{id}

Get a single integration with full details.

Authentication: Required

Path Parameters:

Parameter	Type	Description
id	string	Integration ID or slug

Response:

{
  "id": "integration-abc-123",
  "name": "Google Drive - Engineering",
  "slug": "google-drive-engineering",
  "type": "google-drive",
  "category": "storage",
  "description": "Integration with Google Drive for document sync",
  "mode": "per-user",
  "authType": "oauth2",
  "embedded": false,
  "clientId": "123456789-abcdefg.apps.googleusercontent.com",
  "scope": "https://www.googleapis.com/auth/drive.readonly",
  "authUri": "https://accounts.google.com/o/oauth2/v2/auth",
  "tokenUri": "https://oauth2.googleapis.com/token",
  "revocationUri": "https://oauth2.googleapis.com/revoke",
  "apiBaseUri": "https://www.googleapis.com/drive/v3",
  "imageUrl": "/images/google-drive.png",
  "data": {},
  "createdAt": "2024-01-15T09:00:00Z",
  "updatedAt": "2024-02-08T14:00:00Z",
  "_links": {
    "self": { "href": "/api/integrations/integration-abc-123" },
    "inf:icon": { "href": "/api/integrations/integration-abc-123/icon" },
    "inf:connect": { "href": "/api/integrations/integration-abc-123/connect" },
    "inf:connection": { "href": "/api/integrations/integration-abc-123/connection" },
    "inf:request": { "href": "/api/integrations/integration-abc-123/request" },
    "inf:integration-owner": { "href": "/api/integrations/integration-abc-123/owner" },
    "inf:integration-shares": { "href": "/api/integrations/integration-abc-123/shares" },
    "inf:integration-share": { "href": "/api/integrations/integration-abc-123/shares/{principalId}", "templated": true }
  }
}

Sensitive Data

clientSecret is never returned in responses for security. It's encrypted at rest and only accessible to server-side code.

---

POST /api/integrations

Create a new integration.

Authentication: Required

Permissions: Requires permission.integrations.create

Request Body:

Field	Type	Required	Description
id	string (UUID)	No	Pre-generated integration ID
name	string	Yes	Integration name
type	string	Yes	Integration driver type
category	string	No	Category (e.g., storage, communication)
description	string	No	Integration description
mode	string	No	Connection mode: per-user (default) or shared
authType	string	No	Auth type: oauth2 (default), apikey, basic, bearer
scope	string	No	OAuth scopes (space-separated)
authUri	string	No	OAuth authorization endpoint
tokenUri	string	No	OAuth token endpoint
revocationUri	string	No	OAuth revocation endpoint
apiBaseUri	string	No	Base URL for API requests
clientId	string	No	OAuth client ID
clientSecret	string	No	OAuth client secret
basicTokenAuth	boolean	No	Use Basic auth for token requests
apiKey	string	No	API key (for authType: apikey)
apiKeyLocation	string	No	API key location: header or query
apiKeyName	string	No	API key parameter/header name
imageUrl	string	No	Integration icon URL
headers	object	No	Custom headers to send with proxied requests (supports variable expansion)
data	object	No	Driver-specific configuration

Custom Headers with Variable Expansion

The headers field accepts an object of key-value pairs that are sent with every proxied request through this integration. Header values support variable expansion using ${...} syntax:

Variable	Resolves To
${user.username}	Authenticated user's username
${user.displayName}	Authenticated user's display name
${user.email}	Authenticated user's email address
${user.<fieldName>}	Custom user field value
${tenant.id}	Current tenant identifier
${tenant.<fieldName>}	Tenant setting value

{
  "headers": {
    "X-User-Email": "${user.email}",
    "X-Tenant": "${tenant.id}",
    "X-Custom-Region": "${user.region}"
  }
}

Variables are expanded at request time, so each user's proxied requests include their own identity.

Example - OAuth 2.0:

{
  "name": "Google Drive - Engineering",
  "type": "google-drive",
  "category": "storage",
  "description": "Sync engineering documents",
  "mode": "per-user",
  "authType": "oauth2",
  "scope": "https://www.googleapis.com/auth/drive.readonly",
  "authUri": "https://accounts.google.com/o/oauth2/v2/auth",
  "tokenUri": "https://oauth2.googleapis.com/token",
  "apiBaseUri": "https://www.googleapis.com/drive/v3",
  "clientId": "123456789-abcdefg.apps.googleusercontent.com",
  "clientSecret": "GOCSPX-xyz123abc456"
}

Example - API Key:

{
  "name": "Custom API Integration",
  "type": "custom",
  "authType": "apiKey",
  "apiKey": "sk-abc123xyz789",
  "apiKeyLocation": "header",
  "apiKeyName": "X-API-Key",
  "apiBaseUri": "https://api.example.com/v1"
}

Response:

201 Created

{
  "id": "integration-abc-123",
  "name": "Google Drive - Engineering",
  "type": "google-drive",
  "mode": "per-user",
  "authType": "oauth2"
}

---

PUT /api/integrations/{id}

Update an existing integration.

Authentication: Required

Permissions: Requires integration:write permission

Path Parameters:

Parameter	Type	Description
id	string	Integration ID or slug

Request Body:

Field	Type	Description
name	string	Updated integration name
scope	string	Updated OAuth scopes
type	string	Integration driver type
category	string	Category
description	string	Description
data	object	Driver-specific data
basicTokenAuth	boolean	Basic auth for token requests
apiBaseUri	string	API base URL
authUri	string	OAuth auth endpoint
tokenUri	string	OAuth token endpoint
revocationUri	string	OAuth revocation endpoint
imageUrl	string	Icon URL
clientId	string	OAuth client ID
clientSecret	string	OAuth client secret
mode	string	Connection mode
authType	string	Auth type
apiKey	string	API key
apiKeyLocation	string	API key location
apiKeyName	string	API key name
headers	object	Custom headers with variable expansion (see POST for details)

Example:

{
  "name": "Updated Integration Name",
  "description": "Updated description",
  "scope": "https://www.googleapis.com/auth/drive https://www.googleapis.com/auth/drive.file"
}

Response:

200 OK with updated integration

---

DELETE /api/integrations/{id}

Delete an integration.

Authentication: Required

Permissions: Requires integration:delete permission

Path Parameters:

Parameter	Type	Description
id	string	Integration ID or slug

Response:

204 No Content

Cascade Delete

Deleting an integration permanently removes all connections and may break libraries or jobs that depend on it.

---

GET /api/integrations/{id}/icon

Get the integration icon image.

Authentication: Required

Path Parameters:

Parameter	Type	Description
id	string	Integration ID or slug

Response:

Binary image stream (PNG, JPEG, SVG, etc.)

---

PUT /api/integrations/{id}/icon

Upload a custom integration icon.

Authentication: Required

Permissions: Requires integration:write permission

Path Parameters:

Parameter	Type	Description
id	string	Integration ID or slug

Request Body:

Binary image data (multipart/form-data)

Response:

200 OK

---

DELETE /api/integrations/{id}/icon

Remove the custom integration icon.

Authentication: Required

Permissions: Requires integration:write permission

Path Parameters:

Parameter	Type	Description
id	string	Integration ID or slug

Response:

204 No Content

---

GET /api/integrations/{id}/account

Get account information for the connected user.

Authentication: Required

Path Parameters:

Parameter	Type	Description
id	string	Integration ID or slug

Response:

{
  "email": "alice@example.com",
  "displayName": "Alice Johnson",
  "accountId": "google-account-123"
}