System Architecture
Core Features
Data Management
Frontend Components
Extensibility
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.
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.
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
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.
Connections represent an active link between an organization and an integration provider. The ConnectionService and ConnectionRepository manage the lifecycle and state of these connections.
A connection can transition through various states: active, paused, error, and disconnected. The system provides explicit actions to manage these states.
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
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.
The CredentialVaultService is responsible for the secure storage, retrieval, and lifecycle management of integration credentials. It employs strong encryption and handles OAuth token refreshing.
All sensitive credentials are encrypted using AES-256-GCM with a derived key. This ensures that credentials are never stored in plain text.
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.
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.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.
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 }.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.
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).The startOAuth endpoint initiates the process by generating a unique state, constructing the authorization URL, and redirecting the user.
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.
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.
The AdminIntegrationsController provides administrative functions to configure platform-wide OAuth client credentials for providers. This is typically done once by platform administrators.
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.
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.
Sources: apps/api/src/integration-platform/controllers/checks.controller.ts:19-74, apps/api/src/integration-platform/controllers/task-integrations.controller.ts:35-132
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
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.
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.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.
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.
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.
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.
The synchronization process typically involves:
The SyncController explicitly supports the following employee synchronization providers:
POST /integrations/sync/google-workspace/employeesPOST /integrations/sync/google-workspace/statusOrganizations can configure which external system acts as their primary source for employee synchronization.
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.
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.
The WebhookController implements a robust signature verification process using HMAC. This protects against tampering and ensures that webhooks originate from trusted sources.
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