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

# Secrets

> The Secrets API lets you provision and rotate the named credentials your actions and workflows reference. It is write-only — a secret value is never returned by any endpoint.

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.

<Warning>
  This API is **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.
</Warning>

## 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
* **Scope required** — `secrets:write` for both endpoints

## Referencing a secret

Once created, use the name in any action header or workflow field:

```
Authorization: Bearer {{secrets.stripe_key}}
```

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

<CardGroup>
  <Card title="Create Secret" icon="plus" href="./create">
    Store a new secret — fails with 409 if the name is taken
  </Card>

  <Card title="Create or Replace Secret" icon="rotate" href="./upsert">
    Idempotent write — creates the secret or rotates its value
  </Card>
</CardGroup>

## 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.