Administration

Secret manager

Manage application-owned Azure vault connections through the Engine.

The Engine owns vault connections and controls access to their secrets. Azure Key Vault stores the secret values. A consuming backend, such as Deeplinq SaaS, keeps its business rules and administration screens.

The current connection type is Azure public-cloud Key Vault, authenticated with an Azure application's client secret. The Azure application, vault and role assignments must already exist. Creating a connection does not grant Azure permissions.

Authority and storage

Use an application credential from a trusted backend. The authenticated credential determines the application; a request cannot select another application. Tenant credentials and engine operator credentials cannot substitute for that application credential.

Connection metadata and encrypted Azure access credentials live in the Engine database. The access credentials use the Engine's existing SECRETS_KEY keyring. They are never returned by connection reads. Payment credential bundles and saved payment tokens stay in Azure, addressed by an exact version.

A connection is restricted to its application, environment, namespace and allowed secret kinds. The initial kinds are payzone_merchant, engine_topup and payment_profile. Two applications cannot claim the same vault, environment and namespace. No API lists the secret values in a vault.

Set up a connection

The endpoints are under /v1/application/secret-manager:

EndpointPurpose
GET /connectionsList the application's connection metadata.
GET /connections/{id}Read connection metadata, secret-version metadata and recent administration history.
POST /connections/actionsCreate, edit, test or change a connection.
POST /operationsRead or write an exact scoped secret through an active connection.
POST /connections/importTransfer an existing connection without changing its cloud references.

Create a draft, submit its Azure client secret, test the connection, then activate it. Authentication, read permission and write permission are recorded separately. A replacement credential is staged and tested before it takes over; the working credential remains in use until the replacement is committed.

Administration requests carry action, input, actorId and reauthenticatedAt. The actor is attribution asserted by the trusted backend, not an independently verified end-user identity. The backend must check the current user's permissions and recent sign-in before using its application credential. Sensitive Engine actions additionally require a reason and a recent authentication timestamp.

Supported actions are create, edit, stageSecret, test, discard, revoke, allowKind, activate, commit, disable, enable and archive. Edits carry the connection's expectedRevision; stale changes are refused.

Only an unused, never-activated draft can be archived. An activated or imported connection can be disabled instead. This preserves references held in consuming services, whose absence the Engine cannot prove atomically.

Use a secret

Operations carry an explicit reference with instance, cloud, environment, namespace, kind and name. Reads and disables name an immutable version; an empty version or latest is refused. Binary values are base64-encoded for transport. These responses are backend-only and must never be forwarded to a browser, model prompt, log or general administration screen.

The operations are create, add_version, find_write, read and disable. Writes use a stable requestToken. If a response is uncertain, reconcile that same write before retrying; do not generate a new token and write blindly. An unresolved receipt does not expire. A matching version resolves it; find_write returning null leaves it reserved because an earlier cloud request could still finish. There is no force-retry operation. Creating a cloud version does not select it for a payment. The consuming backend owns publication of the chosen version and its payment rules.

An Engine or Azure outage is a failure, not an empty directory or permission to use older credentials. A backend that needs a secret cannot complete that operation until access is restored. Configure request deadlines so the backend allows the Engine's bounded cloud operation to finish.

Transfer existing SaaS connections

Deploy Engine support first. Use the SaaS operator import command to transfer existing connection IDs, version metadata, history and Azure access credentials over the authenticated backend connection. Engine reseals the access credentials with its own key. The importer checks the imported metadata and leaves the original SaaS records intact. Identical repeated imports are safe; conflicting records are refused.

Pause configuration changes and drain cloud writes before import, and keep them paused through cutover. History travels in batches of at most 100 events; an interrupted transfer can replay already accepted batches without duplicates. Pending imports are hidden and cannot serve secret operations. The importer checks the source again before explicitly finalizing the connection.

SaaS uses SECRET_MANAGER_OWNER=engine by default. Existing local connections must be imported before cutover. SECRET_MANAGER_OWNER=legacy_saas is an explicit rollback setting, never an automatic outage fallback. Once a connection changes under Engine ownership, reconcile those changes before using the old SaaS copy. Existing environment-defined multicloud vaults require a separate migration and are refused in Engine mode.

The SaaS backend still receives a payment secret when it must call the payment provider. Engine ownership centralizes storage access; it does not remove the secret from the service that uses it.

On this page