> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hexagon.autos/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage and rotate protected credentials

Identify what you are changing: an application Token, upstream credential, registry Secret, or database encryption key. They have different lifecycle operations.

See [access control](https://docs.hexagon.autos/en/operate/access-control.md) for application Tokens. This page covers managed Secrets referenced by protected connections. Values are write-only through the API, not retrievable backups.

## Inventory dependencies

Query `secret(secret_id)` for metadata and dependent connections/Harnesses. Record readiness, enabled state, active Sessions, and cleanup responsibilities. Settle work before planned rotation. Upstream revocation remains an upstream operation; Hexagon does not automatically remove account permissions there.

## Replace and revalidate

With an owner client and private environment input:

```python theme={null}
import os
client.update_secret(secret_id, value=os.environ['REPLACEMENT_SECRET'])
for connection_id in dependent_connection_ids:
    result = client.validate_connection(connection_id)
    if result['status'] != 'ready':
        raise RuntimeError('Dependent connection remains disabled')
    client.update_connection(connection_id, enabled=True)
```

```typescript theme={null}
const replacement = process.env.REPLACEMENT_SECRET;
if (!replacement) throw new Error('Missing replacement secret');
await client.updateSecret(secretId, { value: replacement });
for (const id of dependentConnectionIds) {
  const result = await client.validateConnection(id);
  if (result.status !== 'ready') throw new Error('Dependent connection remains disabled');
  await client.updateConnection(id, { enabled: true });
}
```

Dependency IDs come from the prior reference inventory. Changing value or enabled state transactionally disables dependent connections, clears validation, and increments versions. Revalidating the list is not one transaction; retain partial progress on failure.

Create fresh Sessions for the new policy version. Do not assume old pinned grants migrate automatically. Already-admitted upstream operations may finish and cannot be undone through revocation.

## A two-connection rotation example

Suppose one managed Secret is referenced by model connection A and protected HTTP connection B. Record both connection IDs and versions before changing the value. The update copies the replacement into each dependent connection's encrypted credential, moves each to draft/disabled, clears validation and increments its version. A name-only Secret edit does not perform this dependent-connection invalidation.

If A validates but B fails, enable only A after its successful check and leave B disabled. Record the partial result; do not mark the rotation complete or replay an interrupted business write to test B. After fixing B's upstream access, validate and enable it explicitly. Use new Sessions for the changed model/protected HTTP versions and confirm real authorized access plus cleanup.

For model/protected HTTP grants, authorization checks the current connection version on each subsequent request. An old grant therefore fails after rotation even if the connection is enabled again. Issuing a new grant through an old Session can return `session_connection_changed` because the Session pins the prior version. Already admitted requests are a separate case and may complete. Tool authorization recovery follows the [Tool-specific flow](https://docs.hexagon.autos/en/build/tool-authorization.md); do not infer it from the model/HTTP grant rule.

The metadata dependency list is an inventory aid, not proof that no other work exists: its Session view is bounded and selected through pinned connection definitions. Reconcile active work and resource cleanup independently. This example is a proposed rotation exercise; it was not run against a live upstream in this review.

The [dedicated connection replacement exercise](https://github.com/NexusFox88/docs/blob/main/resources/testing/evidence/2026-11-20-docs-credential-rotation-cloud.json) replaced an inert test credential with an authorized model credential, observed the draft/disabled version change, revalidated and enabled it, and completed a new Vercel/Pi task. The Session closed, create/delete operations completed, and the test connection was deleted; the original shared connection version was unchanged. This demonstrates Hexagon connection credential replacement, not upstream account key issuance/revocation or encryption-key rotation.

## Disable, delete, and registry references

Disabling does not delete the upstream account. Undeleted connection or Harness image references prevent deletion with `secret_in_use`. Do not bypass this by editing database references.

Registry Secrets serve permitted image pull paths and are read for subsequent provisioning, not injected as ordinary Agent environment. Verify new pulls, private-registry capability, and existing registration references separately.

## Encryption key recovery

These APIs rotate upstream values, not the encryption master key. They do not expose a general master-key rotation workflow. Replacing master.key or hosted HEXAGON\_MASTER\_KEY can make existing encrypted data unreadable; do not try it as troubleshooting.

Back up matching database, key, and deployment identity privately. Logical Secret deletion may retain historical encrypted envelopes; it is not physical erasure.

Verify new Sessions can access the allowed service, old grants reject subsequent requests, dependencies are individually revalidated, and original secrets are absent from logs/guest environment. Sources: [managed Secrets](https://github.com/NexusFox88/docs/blob/main/resources/modules/credentials/managed-secrets.ts), [credential boundary](https://github.com/NexusFox88/docs/blob/main/resources/docs/secret-management.md). Next: [connection lifecycle](https://docs.hexagon.autos/en/build/connection-lifecycle.md), [backup and restore](https://docs.hexagon.autos/en/operate/backup-restore.md), [security boundaries](https://docs.hexagon.autos/en/concepts/security-boundaries.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.