Skip to main content
doc0blade47/compdocumentation home
Sign in

Platform Integrations

Last updated Oct 11, 2026
Relevant source files

The following files were used as context for generating this wiki page:

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

MethodPathDescription
GET/integrations/connections/providersList all available integration providers.
GET/integrations/connections/providers/:slugGet 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

MethodPathDescription
GET/integrations/connectionsList connections for an organization.
GET/integrations/connections/:idGet details for a specific connection.
POST/integrations/connectionsCreate a new connection (API Key/Custom auth).
POST/integrations/connections/:id/pausePause a connection.
POST/integrations/connections/:id/resumeResume a paused connection.
POST/integrations/connections/:id/disconnectDisconnect (soft delete) a connection.
DELETE/integrations/connections/:idDelete a connection permanently.
PATCH/integrations/connections/:idUpdate connection metadata (e.g., connectionName, regions).
POST/integrations/connections/:id/testTest a connection's credentials.
POST/integrations/connections/:id/ensure-valid-credentialsEnsure credentials are valid, refreshing OAuth tokens if needed.
PUT/integrations/connections/:id/credentialsUpdate credentials for a custom auth connection.

Sources: apps/api/src/integration-platform/controllers/connections.controller.ts:150-484

AWS Credential Validation

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 a string | 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

MethodPathDescription
GET/integrations/oauth-appsList custom OAuth apps for an organization.
GET/integrations/oauth-apps/setup/:providerSlugGet OAuth app setup info for a provider.
POST/integrations/oauth-appsSave custom OAuth app credentials for an organization.
DELETE/integrations/oauth-apps/:providerSlugDelete 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

MethodPathDescription
GET/admin/integrationsList all integrations with credential status.
GET/admin/integrations/:providerSlugGet details for a specific integration.
POST/admin/integrations/credentialsSave platform credentials for an integration.
DELETE/admin/integrations/credentials/:providerSlugDelete 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

MethodPathDescription
GET/integrations/checks/providers/:providerSlugList available checks for a provider.
GET/integrations/checks/connections/:connectionIdList available checks for a connection.
GET/integrations/tasks/template/:templateId/checksGet checks for a specific task template.
GET/integrations/tasks/:taskId/checksGet checks for a specific task.
GET/integrations/tasks/:taskId/runsGet 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 the run-connection-checks task if canAutoRunChecks returns 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

MethodPathDescription
GET/integrations/variables/providers/:providerSlugGet all variables required for a provider's checks.
GET/integrations/variables/connections/:connectionIdGet variables for a specific connection (with current values).
POST/integrations/variables/connections/:connectionIdSave 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:

  1. Retrieving valid credentials for the connection (refreshing OAuth tokens if necessary).
  2. Fetching a list of users from the external service.
  3. Identifying active, inactive, or suspended users.
  4. Creating new users and members in the platform for active external users.
  5. Reactivating existing members if they were previously deactivated but are now active externally.
  6. 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

MethodPathDescription
GET/integrations/sync/employee-sync-providerGet the current employee sync provider for an organization.
POST/integrations/sync/employee-sync-providerSet 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.
Security Best Practice

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

MethodPathDescription
POST/integrations/webhooks/:providerSlug/:connectionIdReceives and processes incoming webhooks for a specific connection.

Sources: apps/api/src/integration-platform/controllers/webhook.controller.ts:33-100

Was this page helpful?