OAuth Connections

OAuth authorization flow and connection management.

GET /api/integrations/{id}/connect

Initiate OAuth authorization flow (redirects to OAuth provider).

Authentication: Required

Path Parameters:

Parameter	Type	Description
id	string	Integration ID or slug

Response:

302 Redirect to OAuth provider's authorization page

OAuth Flow:

1. User clicks "Connect" in UI
2. Frontend calls GET /api/integrations/{id}/connect
3. Server generates OAuth state and redirects to provider
4. User authorizes application on provider's site
5. Provider redirects back to GET /oauth2/callback?code=...&state=...
6. Server exchanges code for access/refresh tokens
7. Connection is created and stored

State Parameter

The server automatically generates and validates the OAuth state parameter for CSRF protection.

---

POST /api/integrations/{id}/connect

Programmatically create a connection (alternative to OAuth redirect flow).

Authentication: Required

Request Body:

Integration-specific authentication data (e.g., authorization code, refresh token)

Response:

201 Created with connection details

---

GET /oauth2/callback

OAuth callback endpoint (handled automatically by provider redirects).

Authentication: Not required (public endpoint)

Query Parameters:

Parameter	Type	Description
code	string	Authorization code from provider
state	string	State parameter for CSRF validation
error	string	Error code if authorization failed
error_description	string	Human-readable error description

Response:

302 Redirect to success or error page

Automatic Handling

This endpoint is called automatically during the OAuth flow. Frontend applications don't need to call it directly.

---

GET /api/integrations/{id}/connection

Get the current connection for an integration.

Authentication: Required

Path Parameters:

Parameter	Type	Description
id	string	Integration ID or slug

Response:

{
  "id": "conn-abc-123",
  "integrationId": "integration-abc-123",
  "ownerId": "alice",
  "isShared": false,
  "tokenExpiresAt": "2024-02-10T14:30:00Z",
  "refreshTokenExpiresAt": "2024-03-10T14:30:00Z",
  "lastAuthorizedAt": "2024-02-09T10:00:00Z",
  "apiBaseUri": "https://www.googleapis.com/drive/v3",
  "data": {},
  "createdAt": "2024-01-15T09:00:00Z",
  "updatedAt": "2024-02-09T10:00:00Z"
}

Connection Modes

For per-user integrations, returns the current user's connection. For shared integrations, returns the shared connection.

---

DELETE /api/integrations/{id}/connection

Disconnect and revoke the connection.

Authentication: Required

Permissions: User must own the connection (or be superuser)

Path Parameters:

Parameter	Type	Description
id	string	Integration ID or slug

Response:

204 No Content

Side Effects:

• Access token is revoked with the provider (if revocationUri is configured)
• Connection record is deleted from database
• Any libraries or jobs using this integration will fail until reconnected

Impact

Disconnecting an integration may break libraries, jobs, or other features that depend on it.

---

GET /api/integration-connections

List all connections for the current user across all integrations.

Authentication: Required

Response:

{
  "_links": {
    "self": { "href": "/api/integration-connections" }
  },
  "_embedded": {
    "inf:integration-connection": [
      {
        "id": "conn-abc-123",
        "integrationId": "integration-abc-123",
        "ownerId": "alice",
        "isShared": false,
        "tokenExpiresAt": "2024-02-10T14:30:00Z",
        "lastAuthorizedAt": "2024-02-09T10:00:00Z",
        "_embedded": {
          "inf:integration": {
            "id": "integration-abc-123",
            "name": "Google Drive - Engineering",
            "type": "google-drive"
          }
        }
      }
    ]
  },
  "start": 0,
  "count": 1,
  "total": 1
}

---

POST /api/integrations/{id}/request

Proxy an authenticated request through an integration.

Authentication: Required

Permissions: User must have a valid connection

Path Parameters:

Parameter	Type	Description
id	string	Integration ID or slug

Request Body:

Field	Type	Required	Description
method	string	No	HTTP method (default: GET)
url	string	Yes	Relative or absolute URL
headers	object	No	Additional request headers
data	any	No	Request body (for POST/PUT)

Example:

{
  "method": "GET",
  "url": "/files?pageSize=10",
  "headers": {
    "Accept": "application/json"
  }
}

Response:

Proxied response from the external API

Use Cases:

• Call integration APIs without managing tokens
• Automatic token refresh if expired
• Unified error handling
• Rate limiting and retry logic

---

GET /api/integrations/{id}/request/{path*}

Proxy a GET request through an integration (path-based alternative).

Authentication: Required

Permissions: User must have a valid connection

Path Parameters:

Parameter	Type	Description
id	string	Integration ID or slug
path	string	Relative API path

Example:

GET /api/integrations/my-integration/request/files?pageSize=10

Proxies to the integration's apiBaseUri + /files?pageSize=10

Response:

Proxied response from the external API