Relevant source files
The following files were used as context for generating this wiki page:
- apps/api/src/integration-platform/controllers/task-integrations.controller.ts
- apps/api/src/integration-platform/controllers/connections.controller.ts
- apps/api/src/integration-platform/controllers/checks.controller.ts
- apps/api/src/integration-platform/controllers/admin-integrations.controller.ts
- apps/api/src/integration-platform/controllers/oauth-apps.controller.ts
- apps/api/src/integration-platform/controllers/oauth.controller.ts
- apps/api/src/integration-platform/controllers/sync.controller.ts
- apps/api/src/integration-platform/controllers/variables.controller.ts
- apps/api/src/integration-platform/controllers/webhook.controller.ts
- apps/api/src/integration-platform/services/connection.service.ts
- apps/api/src/integration-platform/services/auto-check-runner.service.ts
- apps/api/src/integration-platform/services/credential-vault.service.ts
- apps/api/src/integration-platform/repositories/provider.repository.ts
- apps/api/src/integration-platform/utils/credential-utils.ts
The Platform Integrations module provides a robust framework for connecting to external services, managing credentials securely, performing automated checks, synchronizing employee data, and handling webhooks. It abstracts the complexities of various authentication mechanisms (OAuth2, API Key, Custom) and offers a standardized way to interact with diverse third-party platforms. The system is designed to be extensible, allowing new integrations to be added via "manifests" that define their capabilities, authentication methods, and checks.
At its core, the module facilitates the creation and management of Connections between an organization and an IntegrationProvider. It ensures that sensitive Credentials are encrypted and handled safely, automatically refreshing OAuth tokens when necessary. Automated Checks can be run against these connections to validate configurations or monitor compliance, with results stored and associated with specific tasks. Additionally, the platform supports Employee Synchronization from HRIS/IDP systems and processes incoming Webhooks to react to external events.
1. Integration Providers and Manifests
Integration providers represent external services (e.g., AWS, Google Workspace, Rippling) that the platform can connect to. Each provider is defined by a "manifest" which outlines its capabilities, authentication requirements, available checks, and other metadata. The system dynamically loads these manifests to present available integrations and configure their behavior.
1.1 Provider Data Model
The ProviderRepository interacts with the IntegrationProvider Prisma model to store metadata about each provider, such as its slug, name, category, capabilities, and whether it's active. This allows the system to persist information about available integrations independently of their manifest definitions.
Sources: apps/api/src/integration-platform/repositories/provider.repository.ts:10-40, apps/api/src/integration-platform/controllers/connections.controller.ts:40-45
1.2 Provider Listing and Details
The ConnectionsController exposes endpoints to list all available integration providers or retrieve details for a specific one. These endpoints aggregate information from the loaded manifests and, for OAuth providers, check if platform-level credentials have been configured.
API Endpoints
| Method | Path | Description |
|---|---|---|
GET | /integrations/connections/providers | List all available integration providers. |
GET | /integrations/connections/providers/:slug | Get details for a specific provider. |
Sources: apps/api/src/integration-platform/controllers/connections.controller.ts:47-147
2. Connection Management
Connections represent an active link between an organization and an integration provider. The ConnectionService and ConnectionRepository manage the lifecycle and state of these connections.
2.1 Connection Lifecycle
A connection can transition through various states: active, paused, error, and disconnected. The system provides explicit actions to manage these states.
Sources: apps/api/src/integration-platform/services/connection.service.ts:69-95
2.2 Connection Creation and Updates
Creating a connection involves validating the provider, handling different authentication types (OAuth2, API Key, Custom), and storing credentials securely. For custom integrations like AWS, specific validation steps are performed before the connection is activated.
Sources: apps/api/src/integration-platform/controllers/connections.controller.ts:182-259, apps/api/src/integration-platform/services/connection.service.ts:50-67
API Endpoints
| Method | Path | Description |
|---|---|---|
GET | /integrations/connections | List connections for an organization. |
GET | /integrations/connections/:id | Get details for a specific connection. |
POST | /integrations/connections | Create a new connection (API Key/Custom auth). |
POST | /integrations/connections/:id/pause | Pause a connection. |
POST | /integrations/connections/:id/resume | Resume a paused connection. |
POST | /integrations/connections/:id/disconnect | Disconnect (soft delete) a connection. |
DELETE | /integrations/connections/:id | Delete a connection permanently. |
PATCH | /integrations/connections/:id | Update connection metadata (e.g., connectionName, regions). |
POST | /integrations/connections/:id/test | Test a connection's credentials. |
POST | /integrations/connections/:id/ensure-valid-credentials | Ensure credentials are valid, refreshing OAuth tokens if needed. |
PUT | /integrations/connections/:id/credentials | Update credentials for a custom auth connection. |
Sources: apps/api/src/integration-platform/controllers/connections.controller.ts:150-484
For AWS connections, the ConnectionsController includes a specialized validateAwsCredentials method. This method attempts to assume an IAM role and verify Security Hub enablement across specified regions before a connection is established or updated. This ensures that the provided AWS credentials have the necessary permissions and that the required AWS services are active.
Sources: apps/api/src/integration-platform/controllers/connections.controller.ts:262-390
3. Credential Management and Security
The CredentialVaultService is responsible for the secure storage, retrieval, and lifecycle management of integration credentials. It employs strong encryption and handles OAuth token refreshing.
3.1 Encryption Mechanism
All sensitive credentials are encrypted using AES-256-GCM with a derived key. This ensures that credentials are never stored in plain text.
Sources: apps/api/src/integration-platform/services/credential-vault.service.ts:20-77
3.2 Credential Storage and Retrieval
The CredentialVaultService provides methods to store both OAuth tokens and API key/custom credentials. It manages credential versions, keeping a history and marking old versions as rotated.
Key Functions
storeOAuthTokens(connectionId, tokens): Stores encrypted OAuth access and refresh tokens, along with their expiry.storeApiKeyCredentials(connectionId, credentials): Stores encrypted API key or custom credentials.getDecryptedCredentials(connectionId): Retrieves and decrypts the latest credentials for a given connection.rotateCredentials(connectionId, newCredentials): Marks current credentials as rotated and stores new ones.
Sources: apps/api/src/integration-platform/services/credential-vault.service.ts:80-164
3.3 OAuth Token Refresh
For OAuth2 integrations, the CredentialVaultService automatically handles token refreshing when an access token is expired or nearing expiry. This ensures continuous operation without manual re-authentication.
Sources: apps/api/src/integration-platform/services/credential-vault.service.ts:192-299
3.4 Credential Utilities
The credential-utils.ts file provides helper functions for normalizing credential values, especially when dealing with fields that might be single strings or arrays of strings.
getStringValue(value): Extracts the first string from astring | string[]value.toStringCredentials(credentials): Converts a{ [key: string]: string | string[] }object to{ [key: string]: string }.
Sources: apps/api/src/integration-platform/utils/credential-utils.ts:1-26
4. OAuth Flow Management
The OAuthController orchestrates the OAuth 2.0 authorization code flow, enabling users to grant the platform access to their external accounts. This involves redirecting users to the OAuth provider, handling callbacks, and securely exchanging authorization codes for tokens.
4.1 OAuth State and Credentials
OAuthStateRepository: Stores temporary state parameters (providerSlug,organizationId,userId,codeVerifier,redirectUrl) during the OAuth flow to prevent CSRF attacks and maintain context.OAuthCredentialsService: Manages platform-level (admin-configured) and organization-level (custom app) OAuth client credentials (clientId,clientSecret,scopes).
4.2 Starting the OAuth Flow
The startOAuth endpoint initiates the process by generating a unique state, constructing the authorization URL, and redirecting the user.
Sources: apps/api/src/integration-platform/controllers/oauth.controller.ts:60-149
4.3 OAuth Callback Handling
The oauthCallback endpoint receives the authorization code from the OAuth provider, validates the state, exchanges the code for access and refresh tokens, stores them, and then redirects the user back to the application.
Sources: apps/api/src/integration-platform/controllers/oauth.controller.ts:152-297
4.4 Managing Custom OAuth Apps
The OAuthAppsController allows organizations to configure their own OAuth application credentials for a provider, overriding platform-level credentials. This is useful for providers where custom app creation is common or required.
API Endpoints
| Method | Path | Description |
|---|---|---|
GET | /integrations/oauth-apps | List custom OAuth apps for an organization. |
GET | /integrations/oauth-apps/setup/:providerSlug | Get OAuth app setup info for a provider. |
POST | /integrations/oauth-apps | Save custom OAuth app credentials for an organization. |
DELETE | /integrations/oauth-apps/:providerSlug | Delete custom OAuth app credentials. |
Sources: apps/api/src/integration-platform/controllers/oauth-apps.controller.ts:16-96
4.5 Admin-level OAuth Configuration
The AdminIntegrationsController provides administrative functions to configure platform-wide OAuth client credentials for providers. This is typically done once by platform administrators.
API Endpoints
| Method | Path | Description |
|---|---|---|
GET | /admin/integrations | List all integrations with credential status. |
GET | /admin/integrations/:providerSlug | Get details for a specific integration. |
POST | /admin/integrations/credentials | Save platform credentials for an integration. |
DELETE | /admin/integrations/credentials/:providerSlug | Delete platform credentials for an integration. |
Sources: apps/api/src/integration-platform/controllers/admin-integrations.controller.ts:19-140
5. Automated Checks
The platform can run automated checks against integrated services to verify configurations, monitor compliance, or validate specific conditions. These checks are defined within the integration manifests.
5.1 Check Definition and Listing
Checks are defined within the manifest.checks array, often mapping to specific task templates. The ChecksController and TaskIntegrationsController provide ways to discover and list these checks.
API Endpoints
| Method | Path | Description |
|---|---|---|
GET | /integrations/checks/providers/:providerSlug | List available checks for a provider. |
GET | /integrations/checks/connections/:connectionId | List available checks for a connection. |
GET | /integrations/tasks/template/:templateId/checks | Get checks for a specific task template. |
GET | /integrations/tasks/:taskId/checks | Get checks for a specific task. |
GET | /integrations/tasks/:taskId/runs | Get check run history for a task. |
Sources: apps/api/src/integration-platform/controllers/checks.controller.ts:19-74, apps/api/src/integration-platform/controllers/task-integrations.controller.ts:35-132
5.2 Running Checks
Checks can be triggered manually or automatically. The runCheckForTask and runConnectionChecks methods handle the execution, credential retrieval, and result storage.
Sources: apps/api/src/integration-platform/controllers/task-integrations.controller.ts:135-309, apps/api/src/integration-platform/controllers/checks.controller.ts:77-210
5.3 Auto-Check Runner
The AutoCheckRunnerService determines if checks can be automatically run for a connection (e.g., after creation or credential update) and triggers a background task via Trigger.dev for reliable execution.
Key Functions
canAutoRunChecks(connectionId): Checks if a connection has checks defined and all required variables are configured.tryAutoRunChecks(connectionId): Triggers therun-connection-checkstask ifcanAutoRunChecksreturns true.
Sources: apps/api/src/integration-platform/services/auto-check-runner.service.ts:12-89
6. Variable Management
Integrations can define variables that allow users to customize check behavior or provide configuration values. These variables can have static options or dynamic options fetched from the external service.
6.1 Variable Definition and Values
Variables are defined in the integration manifest at both the provider and check levels. The VariablesController allows retrieving these definitions and managing their values for a specific connection.
API Endpoints
| Method | Path | Description |
|---|---|---|
GET | /integrations/variables/providers/:providerSlug | Get all variables required for a provider's checks. |
GET | /integrations/variables/connections/:connectionId | Get variables for a specific connection (with current values). |
POST | /integrations/variables/connections/:connectionId | Save variable values for a connection. |
Sources: apps/api/src/integration-platform/controllers/variables.controller.ts:32-132
6.2 Dynamic Options Fetching
For variables with dynamic options, the VariablesController can fetch these options from the external service using the connection's credentials. This is useful for populating dropdowns with values like AWS regions, user groups, or other configurable entities.
Sources: apps/api/src/integration-platform/controllers/variables.controller.ts:135-249
7. Employee Synchronization
The SyncController provides functionality to synchronize employee data from various HRIS/IDP systems (e.g., Google Workspace, Rippling, Ramp, JumpCloud) into the platform. This ensures that the platform's user base is kept up-to-date with external systems.
7.1 Synchronization Process
The synchronization process typically involves:
- Retrieving valid credentials for the connection (refreshing OAuth tokens if necessary).
- Fetching a list of users from the external service.
- Identifying active, inactive, or suspended users.
- Creating new users and members in the platform for active external users.
- Reactivating existing members if they were previously deactivated but are now active externally.
- Deactivating members in the platform if they are inactive, suspended, or removed from the external system.
Sources: apps/api/src/integration-platform/controllers/sync.controller.ts:25-885
7.2 Supported Sync Providers
The SyncController explicitly supports the following employee synchronization providers:
- Endpoint:
POST /integrations/sync/google-workspace/employees - Status Check:
POST /integrations/sync/google-workspace/status - Details: Fetches users via Admin SDK Directory API, handles OAuth token refresh, and manages user/member lifecycle based on Google Workspace user status (active/suspended).
Sources: apps/api/src/integration-platform/controllers/sync.controller.ts:25-885
7.3 Setting Employee Sync Provider
Organizations can configure which external system acts as their primary source for employee synchronization.
API Endpoints
| Method | Path | Description |
|---|---|---|
GET | /integrations/sync/employee-sync-provider | Get the current employee sync provider for an organization. |
POST | /integrations/sync/employee-sync-provider | Set the employee sync provider for an organization. |
Sources: apps/api/src/integration-platform/controllers/sync.controller.ts:888-963
8. Webhook Handling
The WebhookController is responsible for receiving and processing incoming webhooks from integrated services. It includes mechanisms for signature verification to ensure the authenticity and integrity of webhook payloads.
8.1 Webhook Processing Flow
When a webhook is received, the system first identifies the provider, verifies the connection, and then, if configured, validates the webhook's signature using a shared secret. If the signature is valid, the webhook payload is passed to the integration's custom handler for processing.
Sources: apps/api/src/integration-platform/controllers/webhook.controller.ts:33-100
8.2 Signature Verification
The WebhookController implements a robust signature verification process using HMAC. This protects against tampering and ensures that webhooks originate from trusted sources.
Key Functions
extractSignature(headers, headerName): Extracts the signature string from request headers.parseSignatureValue(signature): Parses signature values that might include prefixes (e.g.,sha256=...).verifyHmac(rawBody, secret, algorithm, providedSignature): Performs a timing-safe HMAC verification against the raw request body and a stored secret.
Using timingSafeEqual for comparing HMAC signatures is crucial to prevent timing attacks, where an attacker could deduce parts of the secret by measuring the time it takes for the comparison function to return.
Sources: apps/api/src/integration-platform/controllers/webhook.controller.ts:18-30, apps/api/src/integration-platform/controllers/webhook.controller.ts:102-132
API Endpoints
| Method | Path | Description |
|---|---|---|
POST | /integrations/webhooks/:providerSlug/:connectionId | Receives and processes incoming webhooks for a specific connection. |
Sources: apps/api/src/integration-platform/controllers/webhook.controller.ts:33-100
On This Page
1. Integration Providers and Manifests1.1 Provider Data Model1.2 Provider Listing and DetailsAPI Endpoints2. Connection Management2.1 Connection Lifecycle2.2 Connection Creation and UpdatesAPI Endpoints3. Credential Management and Security3.1 Encryption Mechanism3.2 Credential Storage and RetrievalKey Functions3.3 OAuth Token Refresh3.4 Credential Utilities4. OAuth Flow Management4.1 OAuth State and Credentials4.2 Starting the OAuth Flow4.3 OAuth Callback Handling4.4 Managing Custom OAuth AppsAPI Endpoints4.5 Admin-level OAuth ConfigurationAPI Endpoints5. Automated Checks5.1 Check Definition and ListingAPI Endpoints5.2 Running Checks5.3 Auto-Check RunnerKey Functions6. Variable Management6.1 Variable Definition and ValuesAPI Endpoints6.2 Dynamic Options Fetching7. Employee Synchronization7.1 Synchronization Process7.2 Supported Sync Providers7.3 Setting Employee Sync ProviderAPI Endpoints8. Webhook Handling8.1 Webhook Processing Flow8.2 Signature VerificationKey FunctionsAPI Endpoints