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:
| Endpoint | Purpose |
|---|---|
GET /connections | List the application's connection metadata. |
GET /connections/{id} | Read connection metadata, secret-version metadata and recent administration history. |
POST /connections/actions | Create, edit, test or change a connection. |
POST /operations | Read or write an exact scoped secret through an active connection. |
POST /connections/import | Transfer 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.