Skip to main content
The Secrets API lets you provision and rotate the named credentials your actions and workflows reference. Define a secret once, then point any number of actions at it by name instead of pasting the same token into each one.
Secret values are write-only. No endpoint returns a secret’s value, and there is no secrets:read scope. To change a secret you replace it; to inspect one you cannot — that is the point. A leaked API key can overwrite a credential (which shows up in your audit log) but can never read one back. You can list secret names, so you know what to reference.

​
Key Concepts

  • Name — the reference key, unique per organization. Actions and workflows use it as {{secrets.<name>}}
  • Value — the plaintext credential. Encrypted at rest and substituted server-side at execution time
  • Rotation — writing the same name again replaces the value. Every action referencing it picks up the new value immediately; nothing needs re-pointing
  • Scopes required — secrets:write to create or replace; secrets-keys:read to list names

​
Referencing a secret

Once created, use the name in any action header or workflow field:
OpenCX substitutes the value when the action runs. If the referenced secret does not exist, the whole header is dropped rather than sent half-resolved.

​
Available Endpoints

Create Secret

Store a new secret — fails with 409 if the name is taken

Create or Replace Secret

Idempotent write — creates the secret or rotates its value

List Secret Names

Names and reference counts — never values

​
Deleting a secret

Deletion is available in the dashboard only, under Settings → Secrets. Removing a secret breaks every action still referencing it, so it stays behind the UI that shows you how many actions that is.