secutils-dev/secutils/secrets

Secutils.dev: User Secrets

User secrets are write-only key-value pairs scoped to a single user. The value is encrypted at rest with AES-256-GCM and is never returned through any read endpoint. After creation the only way to read it is indirectly: a responder script, page-tracker extractor, or API-tracker configurator/extractor that was explicitly granted access can read the decrypted value through its context.secrets.* (responders) or context.params.secrets.* (trackers) global.

Static responder body and headers also support ${secrets.KEY} templating; the server expands the placeholder server-side at request time and never exposes the literal value to the responder script even when both mechanisms are in use.

Guide: <https://secutils.dev/docs/guides/platform/secrets>. Full reference: <https://secutils.dev/api-docs/openapi.json>.

Endpoints (tag: user)

Authenticate with the Kratos session cookie or Authorization: Bearer su_ak_<token> (see secutils-api-keys).

Create-secret payload

{
  "name": "THIRD_PARTY_API_KEY",
  "value": "sk-prod-..."
}

Naming rules (enforced server-side):

• Must start with a letter ([a-zA-Z]).
• May contain letters, digits, underscores, and hyphens.
• Max 128 characters.
• Must be unique per user.

value max length is 10 KB. Successful response is the created UserSecret metadata (id, name, timestamps). The value field is never echoed back.

Update-secret payload

{ "name": "THIRD_PARTY_API_KEY", "value": "sk-prod-new-..." }

Both fields are optional. Sending only name renames in place; sending only value rotates the secret; sending both renames and rotates.

When a value rotates, Secutils automatically re-syncs the decrypted value to every page tracker that lists this secret under its secrets: "all" or secrets: { "selected": [...] } access list. Responders resolve secrets at request time, so they always see the latest value without any sync.

Granting access to a responder or tracker

The secrets field on a responder, page tracker, or API tracker controls which secrets are decrypted into its sandbox:

"secrets": "none"                       // default - no secrets exposed
"secrets": "all"                        // every user secret is exposed
"secrets": { "selected": ["<id1>", "<id2>"] }   // explicit allow-list

For the selected mode the array contains the id field from GET /api/user/secrets (not the name). Deleting a secret removes its id from every selected list automatically.

Accessing secrets at runtime

Missing or non-granted secrets resolve to undefined in scripts and to the literal ${secrets.MY_KEY} placeholder in static bodies (the server leaves the unresolved placeholder in place so the failure is visible to the consumer).

Example flow (curl)

SECRET=$(curl -sX POST https://secutils.dev/api/user/secrets \
  -H "Authorization: Bearer $SECUTILS_API_KEY" \
  -H "content-type: application/json" \
  -d '{"name":"THIRD_PARTY_API_KEY","value":"sk-prod-..."}')
SECRET_ID=$(echo "$SECRET" | jq -r '.id')
 
# Create a responder that's allowed to read this one secret
curl -sX POST https://secutils.dev/api/webhooks/responders \
  -H "Authorization: Bearer $SECUTILS_API_KEY" \
  -H "content-type: application/json" \
  -d "$(jq -n --arg sid "$SECRET_ID" '{
    name: "third-party-mock",
    location: {pathType:"=", path:"/"},
    method: "GET",
    enabled: true,
    settings: {
      requestsToTrack: 5,
      statusCode: 200,
      headers: [["x-token","Bearer ${secrets.THIRD_PARTY_API_KEY}"]],
      body: "ok",
      secrets: {selected: [$sid]}
    },
    tagIds: []
  }')"

Caveats

• Secrets are user-scoped, never workspace-scoped or shared. There is

no "team secrets" tier.

• File-upload from the UI ends up as a UTF-8 string in value; for

binary secrets, base64 the bytes before storing and decode inside the script.

• Rotating a secret that is referenced by a responder using static

${secrets.X} template substitution takes effect on the next request; no re-deploy needed.

• The 10 KB value limit applies to the post-encryption byte count,

which means base64-encoded binary blobs lose roughly 25% of capacity.

See also

• Human-readable guide: <https://secutils.dev/docs/guides/platform/secrets>
• Related skills: secutils-webhooks, secutils-web-scraping-page,

secutils-web-scraping-api, secutils-deno-runtime

• OpenAPI: <https://secutils.dev/api-docs/openapi.json>