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

# Secrets

> Store, rotate, activate, and resolve sensitive values without embedding them in source.

Secrets keep credentials and sensitive configuration outside Components, templates, logs, and metadata. A Secret has stable metadata and a versioned set of values called revisions.

## Secret model

| Concept      | Meaning                                                                              |
| ------------ | ------------------------------------------------------------------------------------ |
| Secret       | Stable name, category, description, owner, metadata, and lifecycle record.           |
| Revision     | One encrypted value with activation time, active state, version, and audit metadata. |
| Active value | The eligible revision resolved by name during runtime execution.                     |

Use a durable name such as `CRM_API_KEY` or `PAYMENTS_WEBHOOK_SECRET`. Components resolve the name; operators can rotate the underlying value without editing source.

## Create a Secret

1. Open **Security Admin → Secrets**.
2. Choose a unique stable name.
3. Add a category and description that identify the owning system and purpose.
4. Enter the initial value.
5. Decide whether it is active immediately and set an activation time when needed.
6. Save, then grant only the users or service accounts that need to manage or resolve it.

<Warning>
  Do not repeat the Secret value in its name, description, category, or metadata. These fields are designed for discovery and audit, not confidential data.
</Warning>

## Resolve from low-code

```js theme={null}
const apiKey = await api.getSecret('CRM_API_KEY');

const response = await api.httpCall({
  url: 'https://api.example.com/customers',
  method: 'GET',
  headers: {
    Authorization: `Bearer ${apiKey}`,
  },
});

return response.data;
```

Resolve several values together when one integration needs them:

```js theme={null}
const config = await api.getSecrets([
  'CRM_API_URL',
  'CRM_API_KEY',
]);
```

Secret resolution occurs inside trusted runtime execution. Confirm the Secret and an eligible active revision exist in every environment where the Component runs.

## Rotate safely

Rotation adds a new revision under the existing Secret name:

1. Create the new credential in the external system.
2. Add a new Secret revision.
3. Set its activation time or activate it deliberately.
4. Run a controlled integration check with the real execution principal.
5. Disable the previous revision after dependent workloads have switched.
6. Destroy the old revision only after rollback is no longer required.

This keeps Component code and template definitions unchanged during rotation.

<Tip>
  When the external system supports overlapping credentials, keep the old credential valid until the new Secret revision has passed a production-path check.
</Tip>

## Revision actions

| Action       | Effect                                                                  |
| ------------ | ----------------------------------------------------------------------- |
| Add revision | Encrypt and store another value under the stable Secret.                |
| Activate     | Make an eligible revision available to runtime resolution.              |
| Disable      | Remove a revision from active resolution without destroying its record. |
| Reveal       | Display one revision to an authorized operator for an explicit task.    |
| Destroy      | Permanently revoke the stored value for that revision.                  |

Reveal only when a human must copy or compare the value. Most integrations should resolve Secrets inside runtime execution and never expose them to a browser.

## Access control

Secret permissions are independent from Component and Automation permissions:

| Capability   | Typical access                                       |
| ------------ | ---------------------------------------------------- |
| Secret Read  | Inspect accessible Secret metadata and revisions.    |
| Secret Write | Create and rotate accessible Secrets.                |
| Secret Admin | Manage all Secrets and privileged lifecycle actions. |

Non-administrative access is constrained by ownership and current authorization. `INSTANCE_ADMIN` is broader and should be reserved for trusted operators.

Use a dedicated service account for unattended workloads so execution ownership, platform access, and surrounding resource permissions stay independent from a developer account.

## High-level backend mechanism

Secret metadata and revision lifecycle are stored as durable tenant records. Values are encrypted at rest and omitted from normal list and detail projections. Runtime resolution selects an active, time-eligible revision by stable Secret name, decrypts it within the trusted execution boundary, and returns it only to the running workload.

Realtime and Activity can report metadata or lifecycle changes without publishing the value itself. Logs and runtime error paths apply sensitive-data redaction, but application code must still avoid logging the resolved value.

## Secrets in integrations and Agents

* Components should resolve a Secret immediately before the outbound operation that needs it.
* Job templates should store business configuration in `options.input`, not credentials.
* Webhooks should mask sensitive persisted fields; use a Component plus Secret resolution for advanced signing or credential selection.
* Agent tools and MCP connections can reference governed Secret bindings rather than embedding tokens in prompts or tool definitions.
* Storage metadata, database rows, Assistant messages, and Agent memory are not Secret stores.

## Failure behavior

Secret resolution fails when the name does not exist, no active eligible revision is available, or the current principal is not authorized. Treat this as a configuration or access error; do not fall back to a credential embedded in source.

If an integration begins failing after rotation:

1. Confirm the new revision is active and its activation time has arrived.
2. Confirm the workload's actual service account can access the Secret.
3. Check that the external credential is enabled.
4. Inspect sanitized Logs and Trace using the execution identifiers.
5. Re-enable the previous revision only if the external system still accepts it and rollback is intended.

## Production checklist

* Use stable names and purpose-focused descriptions.
* Keep values out of metadata, source, templates, logs, and prompts.
* Resolve at runtime under a least-privilege service account.
* Rotate by adding a revision, not renaming the Secret.
* Use activation timing for coordinated rollout.
* Disable before destroy when rollback may be needed.
* Reveal only for an explicit operational reason.
* Test the real Endpoint, Job, or Agent execution path after rotation.
* Revoke the external credential as well as destroying its RevoEngine revision.

## Related guides

<CardGroup cols={2}>
  <Card title="Runtime API" icon="code" href="/low-code/runtime-api">
    Resolve one or several Secrets from Components.
  </Card>

  <Card title="Identity and access" icon="users-gear" href="/operate/identity-and-access">
    Grant Secret permissions to the real execution principal.
  </Card>

  <Card title="Automation" icon="gears" href="/operate/automation">
    Keep credentials out of Job, Event, and Webhook history.
  </Card>

  <Card title="Security and governance" icon="shield-halved" href="/platform/security-and-governance">
    Apply least privilege and safe evidence handling across the platform.
  </Card>
</CardGroup>