Copy page

User Guides

Secrets

Store credentials once, reference them from any component, and understand what has to be unhooked before a secret can be deleted.

Overview

A secret is an org-scoped named credential. Components never hold credential values inline — they hold a reference to a secret, and Monad resolves it at run time.

Two things to know:

• Values are write-only. The API returns secret metadata — name, description, timestamps, and the resources that reference it — but never the value. Reading a secret back is not possible, so keep your own copy in a secrets manager if you will need it again.
• A referenced secret cannot be deleted. Deletion is refused while anything still points at the secret, and "referenced" is broader than you might expect. See Deleting a secret.

Required Permissions

Permission	Description
secrets:read	List and view secret metadata
secrets:write	Create and update secrets
secrets:delete	Delete secrets that are no longer referenced

For details on assigning these permissions, see the Organization RBAC guide.

Creating a Secret

1. Navigate to your organization and select the Secrets tab.
2. Create the secret, giving it a name and its value.
3. Reference it from a component — input, output, enrichment, or transform — by selecting it in the component's credential field.

Via the API, create a secret with POST /v2/{organization_id}/secrets. Authenticate with an API key in the x-api-key header:

Code
curl -X POST https://app.monad.com/api/v2/{organization_id}/secrets \
  -H "x-api-key: $MONAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "splunk-hec-token",
    "description": "HEC token for the security index",
    "value": "00000000-0000-0000-0000-000000000000"
  }'

A 201 returns the secret's metadata. Note that the value is not echoed back:

Code
{
  "id": "3f1c9e64-8a12-4c7d-9f30-1b2c4d5e6f70",
  "organization_id": "9b21338e-73ef-4cc3-bcde-c8b5adaa5125",
  "name": "splunk-hec-token",
  "description": "HEC token for the security index",
  "created_at": "2026-08-05T22:31:04Z",
  "updated_at": "2026-08-05T22:31:04Z"
}

Use that id wherever a component's configuration expects a secret reference.

Sharing a Secret

A top-level organization can share a secret with its teams, so a team can use a credential you manage without ever seeing its value. Secrets are one of five shareable resource types; the Resource Sharing guide covers the full flow.

What is specific to secrets:

• The value stays hidden. A shared secret appears in the receiving team's secret selectors with a Shared with team badge. The team can reference it from its components, but cannot view its value, edit it, or delete it.
• Rotation propagates. Update the value once in the owning organization and every team's components pick up the new value, with no coordination required.
• Teams cannot re-share. A secret shared with your organization cannot be shared onward.
• Unsharing is blocked while the team is using it. Remove the team's use of the secret first; see Unsharing and resources in use.

What Counts as "In Use"

A secret is in use when anything references it, whether or not that thing is running. Five kinds of reference exist:

Reference	Example
Input	an API token on a connector that pulls data
Output	a bot token on a Slack destination
Enrichment	an API key on a lookup provider
Transform	HMAC key material on a mask operation
Pipeline node override	a credential set on a single node of one pipeline, overriding the component's own configuration

Two consequences worth internalizing:

• A disabled pipeline still counts. So does a component that belongs to no pipeline at all. If a component exists and names the secret, the secret is in use.
• "Not currently receiving data" is not the same as "unused." An idle connector holds its reference exactly like a busy one.

Finding What References a Secret

Before deleting, check what points at it with GET /v2/{organization_id}/secrets/{secret_id}:

Code
curl -H "x-api-key: $MONAD_API_KEY" \
  https://app.monad.com/api/v2/{organization_id}/secrets/{secret_id}

The response lists the inputs, outputs, enrichments, and transforms that reference the secret:

Code
{
  "id": "3f1c9e64-8a12-4c7d-9f30-1b2c4d5e6f70",
  "name": "splunk-hec-token",
  "inputs": [],
  "outputs": [{ "id": "7c4e...", "name": "Splunk HEC" }],
  "enrichments": [],
  "transforms": [{ "id": "b91a...", "name": "Mask employee identity" }]
}

GET /v2/{organization_id}/secrets returns the same lists for every secret in the organization, which is the efficient way to audit a whole organization at once:

Code
curl -H "x-api-key: $MONAD_API_KEY" \
  "https://app.monad.com/api/v2/{organization_id}/secrets?limit=100&offset=0"

Two cautions when auditing:

• These lists do not include pipeline-node overrides. A secret referenced only by a node override shows four empty lists here and still cannot be deleted. The deletion error names the pipeline, so you are not left guessing — but an empty pre-check is not a guarantee.
• Paginate. List endpoints return a limited page by default, so pass limit and offset and read to the end. Auditing "which secrets are unused?" from a single unpaginated page will report in-use credentials as unused.

Deleting a Secret

Delete with DELETE /v2/{organization_id}/secrets/{secret_id}:

Code
curl -X DELETE -H "x-api-key: $MONAD_API_KEY" \
  https://app.monad.com/api/v2/{organization_id}/secrets/{secret_id}

Response	Meaning
204	Deleted.
409	Still referenced. The message names every referencing resource.
403	The secret was shared with your organization by another organization; only its owner can delete it.
404	No such secret in this organization.

A 409 looks like this:

Code
{
  "code": 409,
  "error": "Secret cannot be deleted because it is in use by: Outputs: Splunk HEC (type: splunk); Transforms: Mask employee identity"
}

To proceed, edit each named resource to stop referencing the secret — point it at a different secret or clear the field — then delete the secret. Deleting the component also releases its reference.

If the secret is shared with other organizations, remove the shares first — see Sharing a secret.

Rotating a Secret

Update the secret's value in place rather than creating a replacement, so every component that references it picks up the new value without reconfiguration. In the UI, edit the secret and save a new value; via the API, use PATCH /v2/{organization_id}/secrets/{secret_id}:

Code
curl -X PATCH https://app.monad.com/api/v2/{organization_id}/secrets/{secret_id} \
  -H "x-api-key: $MONAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "value": "the-new-value" }'

A 200 returns the secret's metadata, with updated_at advanced. Sending only value leaves the name and description unchanged.

One caveat specific to deterministic operations: the mask transform's deterministic mode derives its output from the key material, so rotating that secret changes every future digest. Values masked before the rotation will no longer match values masked after it. Treat a key used for deterministic masking as long-lived.