Backend Credential Encryption and Storage

Overview

To execute calls against a SOAP backend, the platform requires connection credentials. This document describes the mechanism used to securely store and handle these credentials.

The platform ensures that backend credentials are encrypted at rest and are never exposed in plaintext through the API or logs. The core of this system involves symmetric encryption performed within the platform's PostgreSQL database, with the encryption key managed externally by the API publisher.

This process involves two main components:

• Admin API: Encrypts credentials when an API publisher creates or updates a backend profile.
• Runtime: Decrypts credentials on-demand when executing a call to a backend service.

The plaintext credential material is never persisted in an unencrypted state.

How it works

The credential management process is designed to be write-only from an API perspective, ensuring that secrets, once stored, are never revealed.

Storage and Encryption Mechanism

Backend credentials are stored in the platform's PostgreSQL database within the corresponding backend-profile row. The credential data itself resides inside an encrypted envelope, which is a JSON object with the following structure:

{
  "v": 1,
  "alg": "pgcrypto-aes256",
  "enc": "<base64 ciphertext>"
}

Encryption is handled by the pgcrypto extension for PostgreSQL, using the pgp_sym_encrypt function with the AES-256 symmetric encryption algorithm.

The following diagram illustrates the data flow for creating and using an encrypted credential:

sequenceDiagram
    participant P as API Publisher
    participant Admin as Admin API
    participant DB as PostgreSQL Database
    participant Runtime
    participant Backend as SOAP Backend

    P->>+Admin: POST /backend-profiles (with plaintext credential)
    Admin->>+DB: Encrypt credential with S2R_CREDENTIAL_KEY<br/>(pgp_sym_encrypt)
    DB-->>-Admin: Store encrypted envelope
    Admin-->>-P: Respond with metadata (no plaintext)

    Note over Runtime, Backend: Later, during a request...

    Runtime->>+DB: Fetch encrypted credential for profile
    DB-->>-Runtime: Return encrypted envelope
    Note right of Runtime: Decrypts credential using<br/>S2R_CREDENTIAL_KEY
    Runtime->>+Backend: Call backend with decrypted credential
    Backend-->>-Runtime: SOAP Response

Encryption Key Management

The symmetric encryption key is not stored in the database. Instead, it is supplied to the Admin API and Runtime services at startup via the S2R_CREDENTIAL_KEY environment variable. This key must be sourced from a secure secret store.

Key handling is governed by the following rules:

• The S2R_CREDENTIAL_KEY environment variable must be present at startup. If it is not set, services will refuse to start and will not operate on credentials.
• The Admin API and Runtime services perform a preflight check at startup to confirm that the pgcrypto extension is available and that the provided key is well-formed.
• All services that handle credentials (Admin API, Runtime) must use the same key value.

Write-Only API Behavior

Credential values are write-only. When you create or update a backend profile, the plaintext credential is provided in the request body, but it is never returned in any API response.

Instead of the credential itself, API responses contain a metadata envelope indicating the status of the credential.

Example API Response Snippet:

{
  "credentials": {
    "set": true,
    "lastUpdatedAt": "2026-04-18T14:02:11Z",
    "lastUpdatedBy": "alice@example.gov.il"
  }
}

This design allows clients to confirm if and when a credential was set, but prevents the credential value from ever being exposed. Plaintext credentials are also never written to service logs.

Configuration

Environment Variables

The encryption system is configured via a single environment variable.

Credential Payloads by Authentication Type

The structure of the plaintext credential payload, provided only during create or update operations, varies based on the backend's authentication type. All of the following payloads are encrypted and stored using the S2R_CREDENTIAL_KEY.

API Operations

The platform provides an administrative endpoint to test backend connectivity without exposing stored credentials.

Test a Backend Connection

Safely tests DNS, TCP, and WSDL reachability for a configured backend profile. This operation does not return the stored credential.

• Endpoint: POST /admin/v1/backend-profiles/{profileId}:test-connection

The source does not specify the request or response body for this endpoint.

Troubleshooting

If you encounter these errors after a new deployment, it typically indicates that the key binding was not applied to the new service revision.

See Also

• Security overview
• Network & data residency
• Configure the backend
• Troubleshooting

All SOAP-to-REST docs