Skip to main content
doc0blade47/compdocumentation home
Sign in

Get Platform Secret Key

Last updated Oct 11, 2026
Relevant source files

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

This document outlines the execution flow initiated when a user attempts to test an integration connection from the IntegrationPlatformTestPage in the frontend. The core purpose of this flow is to securely retrieve and decrypt sensitive integration credentials (like API keys or OAuth tokens) from the backend's credential vault, enabling the system to verify the connection's validity.

The process begins with a user action in the browser, triggering an API call to the backend. The backend then fetches the encrypted credentials, decrypts them using a master secret key, and finally uses these plaintext credentials to perform the actual connection test. This secure handling ensures that sensitive information is never exposed directly to the frontend and is only decrypted when needed for operational purposes.

1. IntegrationPlatformTestPage

The execution begins on the IntegrationPlatformTestPage component, which is a React page responsible for rendering the user interface to manage and test integration connections. When a user navigates to this page, it loads and displays a list of available integration providers and existing connections.

When a user clicks the "Test" button associated with a specific connection, this action triggers the handleTestConnection function within this component. The page passes the unique connectionId and providerSlug of the selected connection to this handler. The primary role of this component in this flow is to initiate the client-side interaction that leads to the backend process.

Sources: apps/app/src/app/(app)/[orgId]/integrations/platform-test/page.tsx:329-331

2. handleTestConnection

The handleTestConnection function is an asynchronous client-side handler defined within the IntegrationPlatformTestPage. It is invoked when a user clicks the "Test" button for a particular integration connection.

This function takes the connectionId and providerSlug as arguments. Its main responsibility is to make an API call to the backend to initiate the actual connection test. It uses the testConnection mutation provided by the useIntegrationMutations hook (which internally uses api.post) to send an HTTP POST request to the backend's /v1/integrations/connections/:id/test endpoint. During this process, it updates the isLoading state to provide visual feedback to the user and logs the outcome (success or error message) to the frontend's action log.

Sources: apps/app/src/app/(app)/[orgId]/integrations/platform-test/page.tsx:376-384

3. testConnection

This method is a NestJS controller endpoint (@Post(':id/test')) within the ConnectionsController in the backend. It serves as the API entry point for testing an integration connection.

Upon receiving the POST request from the frontend, the method extracts the connectionId from the URL parameters. It first retrieves the Connection object from the database using this.connectionService.getConnection(id). The crucial step for credential access is then performed: it calls this.credentialVaultService.getDecryptedCredentials(connection.id) to obtain the plaintext credentials required for the test. Depending on the providerSlug (e.g., 'aws'), it might delegate to a specific testing method (this.testAwsConnection) or use a generic handler defined in the integration manifest. If the connection test is successful, it activates the connection; otherwise, it sets the connection to an error state with a descriptive message.

Error Handling

This method handles several potential errors:

  • If the provider is not found for the connection, it throws an HttpException.
  • If no credentials are found for the connection, it throws an HttpException.
  • It catches exceptions during the actual connection test (e.g., network issues to the external service, invalid credentials) and uses this.connectionService.setConnectionError to update the connection's status in the database, providing user-facing error messages.

Sources: apps/api/src/integration-platform/controllers/connections.controller.ts:586-630

4. getDecryptedCredentials

The getDecryptedCredentials method resides within the CredentialVaultService. Its purpose is to retrieve the latest encrypted credentials for a given connectionId and convert them into a usable, plaintext format.

This method takes the connectionId as input. It queries the credentialRepository to fetch the latestVersion of credentials associated with that connection. The retrieved latestVersion contains an encryptedPayload, which is a JSON object where sensitive values are stored as EncryptedData objects (containing encrypted, iv, tag, and salt as base64 strings). The method then iterates through this payload, calling this.decrypt() for each EncryptedData object to transform it back into its original plaintext string. Non-encrypted values are passed through directly. The final output is a Record<string, string | string[]> containing all decrypted credentials.

Sources: apps/api/src/integration-platform/services/credential-vault.service.ts:241-274

5. decrypt

The decrypt method is a private, core cryptographic function within the CredentialVaultService. It performs the actual decryption of a single piece of sensitive data.

This method accepts an EncryptedData object as input. It first calls this.getSecretKey() to retrieve the application's master encryption key. Using this key and the salt from the EncryptedData, it derives the specific cryptographic key required for decryption using scryptSync. It then initializes an aes-256-gcm decipher using createDecipheriv, sets the authentication tag (tag) to verify data integrity, and finally performs the decryption. The result is the original plaintext string.

Sources: apps/api/src/integration-platform/services/credential-vault.service.ts:80-92

6. getSecretKey

The getSecretKey method is a private helper function within the CredentialVaultService. Its sole responsibility is to retrieve the master encryption key required for cryptographic operations.

This method accesses the process.env.SECRET_KEY environment variable. This environment variable holds the critical secret key used to encrypt and decrypt all sensitive credentials stored in the vault.

Critical Configuration

This method is a critical failure point. If the SECRET_KEY environment variable is not set, the method will throw an Error, preventing any decryption operations and effectively rendering the credential vault unusable. This highlights the importance of proper environment configuration for security.

Sources: apps/api/src/integration-platform/services/credential-vault.service.ts:65-71

Sequence Diagram

Flowchart

Key Observations

  • Cross-Module Boundaries: This flow demonstrates a clear separation of concerns across multiple modules and layers:
    • Frontend (apps/app): Handles user interaction and initiates API requests.
    • Backend Controller (apps/api/src/integration-platform/controllers): Acts as the API gateway, receiving requests and orchestrating business logic.
    • Backend Service (apps/api/src/integration-platform/services): Contains core business logic, such as credential management and cryptographic operations.
    • Backend Repository (implicit in CredentialVaultService): Abstracts database interactions for credential storage.
    • Environment Variables: Crucial for secure configuration of the master encryption key.
  • Potential Failure Points:
    • Network failures: Between the frontend and backend, or from the backend to external integration services.
    • Missing or invalid SECRET_KEY: This is a critical configuration error that would prevent all decryption, leading to system-wide credential access failures.
    • Corrupted encrypted data: If the stored EncryptedData is tampered with or malformed, decryption will fail.
    • Database issues: Failure to retrieve connection or credential records.
    • External service unavailability: The actual connection test to the third-party integration might fail due to the external service being down or returning errors.
    • Invalid credentials: Even if decrypted successfully, the credentials might be outdated or incorrect, causing the external connection test to fail.
  • Error Handling:
    • The frontend logs API call results and displays user-friendly messages.
    • The ConnectionsController catches exceptions during the connection test and updates the connection's status in the database (setConnectionError), providing persistent feedback.
    • The CredentialVaultService.getSecretKey explicitly throws an error if the SECRET_KEY is not set, indicating a critical deployment issue.
  • Performance Considerations:
    • The cryptographic operations (scryptSync, createDecipheriv) involved in decryption are CPU-intensive. While generally fast for individual credentials, decrypting a large number of credentials concurrently could introduce latency.
    • Database queries for connection and credential records contribute to the overall response time.
    • The most significant performance variable is often the external API call made during the actual connection test, as its latency depends entirely on the third-party service.
Was this page helpful?