Secrets

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

Open Profile settings → Vault, choose the instance scope with the required administrator or Secret permissions, and create a Secret.
Choose a unique stable name.
Add a category and description that identify the owning system and purpose.
Enter the initial value.
Decide whether it is active immediately and set an activation time when needed.
Save, then grant only the users or service accounts that need to manage or resolve it.

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

Resolve from low-code

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

return response.data;

vault.get() returns a parent and selected revision with its value as a string. Build headers explicitly and protect execution captures. Instance scope is the default; values must remain outside logs and model results. Secret resolution occurs inside trusted runtime execution. Confirm the Secret and an eligible active revision exist in every environment where the Component runs.

Personal Vault and integrations

For the owner, consent, and binding workflow across instance, personal, and organization scopes, see Vault and connected accounts. In Profile settings → Vault, each signed-in user can store personal Secrets and connect an OAuth integration. The owner chooses which Agent plugin or saved code Component may use a named value. A direct Component grant follows its stable Component identity across updates, so review changed code before it runs with the grant. A disconnected and reconnected integration may need a renewed grant. Use await vault.get('NAME', { scope: 'user' }) for a personal Secret, or await vault.getAccessToken('NAME', { scope: 'user' }) for an OAuth access token. Saved consumers retain exact grants and requested-name mapping. See HTTP integrations. Instance administrators can configure shared OAuth integrations for an instance in the same Vault area. Personal and instance connections have separate ownership and access boundaries. An unsaved ad hoc execution cannot use a personal Component grant.

Manage Secrets from low-code

Use one native vault.* manager by name for scope: 'instance' (the default) or scope: 'user'. Both scopes have the same inputs, properties and history.

Method	Behavior
`get`	Parent Secret and selected revision, including plaintext `revision.value` as stored UTF-8 text
`create`	Atomically create a new name and first value; return parent metadata
`update`	Edit parent properties at its metadata version; return parent metadata
`delete`	Delete the whole Secret or one exact timestamp version
`rotate`	Add a new value to an existing name; return parent and revision metadata, without value
`listRevisions`	Page through retained revision metadata without values

const current = await vault.get('TOKEN', { scope: 'user' });
const token = current.revision.value;

const rotated = await vault.rotate('TOKEN', { value: input.newToken }, {
  scope: 'user', validFrom: null,
});
// Rotate returns metadata only. Read the exact written version explicitly.
const selected = await vault.get('TOKEN', {
  scope: 'user', version: rotated.revision.version,
});

validFrom accepts null, a Date, an ISO8601 string or an epoch timestamp in milliseconds (Date.now()). Null or omission means now on writes, the current eligible revision on reads, or whole-Secret deletion. A non-null get/delete selector identifies an exact timestamp; version is an alias. Supplying both requires the same normalized instant. Revision version equals its normalized ISO validFrom. Parent version is a separate numeric metadata update counter. Duplicate timestamp writes conflict; ambiguous retained timestamps fail closed. Immediate rotation retires earlier eligible and scheduled values. A future validFrom schedules the replacement while keeping the current value available. Both scopes retain encrypted history and support category, description and JSON metadata. Explicit get can access a retained disabled revision; deleting its revision removes that access. Only get returns plaintext. Writes have no effect in debug/read-only execution and return null. Automatic trace previews omit Secret values, but never log plaintext yourself. Protect secret-bearing execution request/response capture. Personal lifecycle and value access require the verified account enabled in the executing instance, without owner overrides. A consumption grant cannot manage another owner’s Secret. Instance Secret roles, creator/admin access and total/active quotas still apply. Fresh explicit reads see committed replacements without signing in again; running calls retain resolved inputs. Provider credentials and OAuth consent remain separate lifecycles. See the generated Secrets reference for exact signatures and examples. The public SDK exposes the same manager.

Rotate safely

Both instance Secrets and personal Secrets retain encrypted revisions and support Rotate under a stable name. First create or rotate the credential at the external provider: RevoEngine stores the new value and does not change the provider’s key. For an immediate replacement:

Open the Secret and choose Rotate. In an instance Secret, choosing Rotate from a revision still rotates the whole Secret.
Enter the new value and save. RevoEngine creates an immediately active revision and retires all earlier active revisions, including scheduled ones, atomically.
Run a controlled integration check with the real execution principal.
Revoke the previous credential at the provider when dependent workloads have switched.

History remains. Subsequent reads return the new value without signing in again; calls already in progress retain their previously resolved inputs. Personal Secret grants and existing bindings remain attached to the same name. For a scheduled or overlapping rollout, use Add revision in the Secret editor or a future validFrom through vault.rotate. Adding a revision is additive and does not disable earlier revisions. Review activation timing, verify the integration, then disable the old revisions deliberately.

Where the provider supports overlapping credentials, keep the external old key valid until the new value has passed the real execution-path check. Rotate makes the RevoEngine switch immediate; it does not provide provider-side overlap by itself.

API contracts and limits

The Platform API exposes POST /api/v1/secrets/{secretId}/rotate with a JSON body containing only secret, the new value. It requires Secret Write or Secret Admin and current ownership authorization. It returns 201 with revision metadata, including secretDataId, secretId, active, actDate, version, and audit fields. It returns neither plaintext nor ciphertext. Rotate has no activation-date or inactive-mode argument. The generated Platform API reference contains the request and response schemas. Instance quotas count revisions across all instance Secrets, rather than revisions per name. The total quota includes retained, non-destroyed active and inactive revisions; the active quota includes scheduled active revisions. Rotate requires space for one additional total revision, even when replacing active revisions. The resulting active count must also fit the active quota. A full active quota can allow Rotate when it replaces existing active revisions. Zero blocks growth, invalid quota configuration rejects growth, and there is no unlimited sentinel. Personal Secrets do not use these instance quotas. See Vault and connected accounts for the separate personal-account API and history visibility.

Revision actions

Action	Effect
Add revision	Encrypt and store another value under the stable Secret without retiring previous revisions.
Rotate	Immediately replace every active revision, including scheduled ones, while retaining history.
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:

Confirm the new revision is active and its activation time has arrived.
Confirm the workload’s actual service account can access the Secret.
Check that the external credential is enabled.
Inspect sanitized Logs and Trace using the execution identifiers.
For instance rollback, deliberately disable the replacement and activate the intended earlier revision only if its activation time is eligible and the provider still accepts it. Personal Secret owners can explicitly reveal retained revisions, but there is no dedicated restore action; Rotate again with a known valid value.

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.
Use Rotate for immediate replacement under a stable name.
Use Add revision and activation timing for a 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.

Runtime API

Resolve one or several Secrets from Components.

Identity and access

Grant Secret permissions to the real execution principal.

Automation

Keep credentials out of Job, Event, and Webhook history.

Security and governance

Apply least privilege and safe evidence handling across the platform.

Application interfaces

Data

Files

Automation

Collaboration and realtime

Observability

Identity and security

Secret model

Create a Secret

Resolve from low-code

Personal Vault and integrations

Manage Secrets from low-code

Rotate safely

API contracts and limits

Revision actions

Access control

High-level backend mechanism

Secrets in integrations and Agents

Failure behavior

Production checklist

Runtime API

Identity and access

Automation

Security and governance

​Secret model

​Create a Secret

​Resolve from low-code

​Personal Vault and integrations

​Manage Secrets from low-code

​Rotate safely

​API contracts and limits

​Revision actions

​Access control

​High-level backend mechanism

​Secrets in integrations and Agents

​Failure behavior

​Production checklist

​Related guides

Runtime API

Identity and access

Automation

Security and governance

Secret model

Create a Secret

Resolve from low-code

Personal Vault and integrations

Manage Secrets from low-code

Rotate safely

API contracts and limits

Revision actions

Access control

High-level backend mechanism

Secrets in integrations and Agents

Failure behavior

Production checklist

Related guides