Read an integration's credentials from a manager

Pointing an integration at a secrets manager replaces the credentials stored in Astralis with a reference to a secret in your AWS Secrets Manager or HashiCorp Vault, which Astralis reads each time the integration connects.

Prerequisites

• A manager that reads as Healthy on Settings → Secrets managers.
• Permissions: connection:create_or_update and secrets_manager:read, both held by the Owner and Contributor roles.
• An existing integration. The credentials panel appears when you edit an integration, not while creating it from a template.

Store the credentials in your manager

1. Navigate to Integrations and open the integration.
2. Next to Credentials, click Manage credentials.
3. Choose Read from a manager.
4. Under What this secret must contain, click the copy button to copy the payload template.
5. In your manager, store that JSON as the secret's value, with the placeholders replaced by real values.

Only the keys marked Required must be present. What happens to other keys depends on the integration type: most types ignore them, SaaS integrations pass them to the integration, and email integrations refuse them.

Some integration types keep part of their configuration in Astralis rather than in the secret. The payload template leaves those keys out, and Astralis ignores them if the secret includes them:

Choose the manager and secret

1. Select the Manager. A manager that is failing its checks can be selected, but the integration will not connect until it recovers.
2. Enter the Secret: the secret's name or full ARN in AWS, or its path under the configured mount in Vault.

Check the secret

Click Check. Astralis reads the secret, bypassing its cache, and lists each key the integration needs:

The check never shows values. If the secret does not resolve, the drawer explains why; see troubleshooting secrets managers.

You can save without checking, or after a check that found a problem; the integration then does not connect until the secret is fixed.

Save and test the integration

1. Click Save credentials. Any credentials Astralis had stored for this integration are erased.
2. Back on the integration, the Credentials row reads Read from the manager's name, with the manager's health.
3. Click Test connection. The result reports three stages: Secrets manager reachable, Secret fetched and validated, and Downstream connection.

Rotate a credential

Update the secret in your manager. Astralis picks up the new value within 15 minutes, when its cached copy expires. If the target system rejects a connection first, Astralis fetches the secret again once and retries.

Switch back to credentials entered in Astralis

1. Click Manage credentials and choose Entered in Astralis.
2. Enter the credentials and click Save credentials.

Switching removes the reference. Settings Astralis keeps for the integration type are preserved; the integration has no credentials until you enter them.

Jira ticket integrations

A Jira ticket integration has no Read from a manager option. It reads from a manager through a Jira integration:

1. Point the Jira integration at the manager, as above.
2. Open the Jira ticket integration's Credentials tab.
3. Under Link from existing connector, select the Jira integration and click Link credentials.

The Jira ticket integration then reads the Jira integration's secret, and follows that integration when it changes secret or manager, or switches back to credentials entered in Astralis. Its form shows the manager with a note to unlink in the Credentials tab, and no Manage credentials button.

To switch it back to manual credentials:

1. In its Credentials tab, click Unlink credentials. The integration stays on the manager, now linked to it directly.
2. In its form, click Manage credentials, then Switch to manual.
3. Click Authorize with Jira, or link a Jira integration that does not read from a manager. Until then it has no credentials.

A Jira ticket integration linked to a manager through the API, rather than through a Jira integration, starts at step 2.

What changes for a managed integration

Link through the API

Send PATCH /api/v1/connection with the manager's id (not its key) and the reference:

[
  {
    "key": "billing_postgres",
    "connection_type": "postgres",
    "access": "write",
    "secrets_manager_config_id": "sec_9f2c1b7e-...",
    "secrets_manager_reference": "astralis/billing-postgres"
  }
]

An omitted field keeps its stored value. Set secrets_manager_config_id to null to switch the integration back to credentials entered in Astralis. The response reports failures per integration under failed.

To switch only if nothing changed since you read the integration, send POST /api/v1/connection/{key}/switch-to-manual with the manager's id you read:

{ "expected_secrets_manager_config_id": "sec_9f2c1b7e-..." }

It returns 204 on success, 409 if the integration now reads from another manager or none, and 404 if the integration no longer exists. It changes only the manager link and never creates an integration. It requires connection:create_or_update.

Related

• Troubleshoot secrets managers
• Behavior reference
• Managing integrations