Credential Management
How VersionForge stores, rotates, monitors, and audits connector credentials.
How Credentials Are Stored
VersionForge encrypts all connector credentials at rest using AES-256-GCM encryption with tenant-specific keys. Credentials are decrypted only at sync execution time -- when the connector needs to authenticate with the source or target system -- and are never written to disk in plaintext.
The encryption architecture:
- Each tenant has a unique encryption key derived from a master key using key derivation functions.
- Credentials are stored as encrypted blobs in the database, not in environment variables or config files.
- Decrypted credentials exist only in memory for the duration of the API call and are zeroed out afterward.
VersionForge does not display stored credentials in the UI after initial entry. You can update or replace a credential, but you cannot retrieve the original value. If you need the original, refer to your organization's secret manager.
Adding Credentials
Each connector type requires different credential formats:
| Connector | Credential Type | Required Fields |
|-----------|----------------|-----------------|
| NetSuite | Token-based auth | Account ID, Consumer Key, Consumer Secret, Token ID, Token Secret |
| Workday HCM | OAuth 2.0 | Client ID, Client Secret, Refresh Token, Tenant URL |
| Stripe | API key | Secret Key (starts with sk_) |
| Adaptive Planning | OAuth 2.0 | Client ID, Client Secret, Refresh Token |
| Pigment | API token | API Key, Workspace ID |
| Salesforce | OAuth 2.0 | Client ID, Client Secret, Refresh Token, Instance URL |
To add credentials:
Navigate to the connection
Go to Connections and select the connection you want to configure, or create a new connection.
Enter credentials
Fill in the required fields for the connector type. For OAuth connectors, you can either enter tokens directly or use the OAuth Flow button to authenticate through the provider's consent screen.
Test the connection
Click Test Connection. VersionForge makes a lightweight read-only API call to the source or target system to verify the credentials are valid and have sufficient permissions.
Save
Click Save. The credentials are encrypted and stored. The UI shows a green confirmation and the last-tested timestamp.
Credential Rotation
When you need to rotate credentials (expired token, security policy, compromised key):
- Navigate to the connection and click Update Credentials.
- Enter the new credential values.
- Click Test Connection to verify the new credentials work.
- Click Save. The old credentials are overwritten immediately.
Credential updates take effect on the next sync run. If a sync is currently in progress, it continues using the credentials it loaded at the start of the run. There is no downtime during rotation.
Credential Health Monitoring
VersionForge proactively monitors credential health between sync runs:
- OAuth token expiry tracking -- For OAuth-based connectors, VersionForge tracks the refresh token expiry date and sends a warning notification 7 days before expiry.
- Periodic validation -- Every 6 hours, VersionForge makes a lightweight health check call to each configured connection. If authentication fails, the connection status changes to Credential Error and an alert is sent.
- Revocation detection -- If a token is revoked at the provider (e.g., an admin revokes the Workday OAuth grant), the next health check detects the failure and alerts you immediately.
Health status is visible on the Connections dashboard and the Connection Health Monitoring page.
Revoking Credentials
To remove credentials from a connection:
- Navigate to the connection and click Revoke Credentials.
- Confirm the action. The encrypted credential blob is deleted permanently.
- The connection status changes to No Credentials. Syncs using this connection will fail until new credentials are added.
Audit Log
Every credential-related action is logged in the tenant audit trail:
| Event | Logged Data | |-------|-------------| | Credentials added | User, connection, timestamp | | Credentials updated | User, connection, timestamp | | Credentials revoked | User, connection, timestamp | | Credential test (success) | User, connection, timestamp | | Credential test (failure) | User, connection, timestamp, error type | | Health check failure | Connection, timestamp, error type |
Access the audit log from Settings > Audit Log and filter by event type credential.*.
Never share connector credentials through Slack, email, or ticketing systems. Use your organization's approved secret management process to transfer credentials to the person configuring the connection in VersionForge.