Secrets manager behavior reference

This page defines how Astralis caches values from a secrets manager, behaves during an outage, reports manager health, and exposes managers through the API and deployment settings.

Caching and outages

Each Astralis process keeps its own in-memory cache per manager. Nothing read from a manager is written to disk or the database.

Failures fall into three classes:

When a privacy request step or a connection test fails on a managed integration, Astralis fetches the secret again once and retries, so a rotated credential takes effect without waiting for the cache to expire. Background consent and DataHub tasks retry through a manager outage after 1, 2, and 4 minutes before dropping the work.

Health states

A successful Test does not clear a failure recorded while reading a secret; the next successful read does. A failure of the Astralis deployment's own AWS identity is reported as such and never changes a manager's health.

Scheduled health checks

Astralis checks every manager's reachability every 6 hours, starting one minute after the server starts. A check authenticates to the manager and reads no secret.

Tests and checks

Manager tests and checks are limited to one every 5 seconds per manager.

Payload rules

• The secret is a JSON object (AWS secret string) or a KV object (Vault). AWS binary secrets are refused.
• The keys are the integration type's credential fields, minus settings Astralis keeps for that type. See settings kept in Astralis.
• A key that is empty or null counts as missing.
• Extra keys depend on the integration type. Most types ignore them, SaaS integrations pass them to the integration, and email integrations refuse them. Jira ticket integrations refuse OAuth keys and ignore the rest.
• If the secret includes a key Astralis keeps for the type, the value stored in Astralis wins.
• Values from the secret override tokens Astralis refreshed and stored for the integration, such as OAuth access tokens, key by key.

Eligible integration types

By default, every integration type with credential fields can read them from a manager. A self-hosted deployment narrows this with FIDESPLUS__SECRETS_MANAGER__ELIGIBLE_CONNECTION_TYPES, a JSON array of connection types:

Removing a type refuses new links and makes existing links of that type fail. Unknown type names stop the server from starting. Restart the web server and every worker after changing the value.

Deleting a manager

A manager cannot be deleted while any integration reads from it, including integrations in other organizations. The delete dialog lists the integrations in your organization and counts the rest. Point each one at another manager, or switch it to credentials entered in Astralis, then delete.

Deleting removes the manager's configuration from Astralis. Nothing in your secrets manager changes. A connection that already holds a value in memory may finish its current operation.

Organizations

A manager belongs to the organization that created it. A manager created at the root is usable by every organization but changeable only by its owner. Manager keys are unique across all organizations.

API

All endpoints are under /api/v1/plus.

Callers without secrets_manager:create_or_update, or outside the owning organization, receive managers with details empty and details_redacted: true. Secret values, the Vault secret ID, and the Vault token are never returned. An integration's secrets_manager_reference is returned only to callers with connection:create_or_update.

The payload template for a type is at GET /api/v1/connection_type/{type}/secrets-template and returns 404 until a manager is configured.

Manager details

The ExternalId is generated by Astralis and cannot be set. reference_prefix must end in / or :.

Deployment settings

Self-hosted deployments configure secrets managers with these environment variables, also listed in the configuration reference. An invalid value stops the server from starting.