Secrets

Secrets let you store sensitive values (API keys, tokens, passwords) that your jobs need without hardcoding them in job definitions.

How secrets work

You create a secret with a name and value.
TrigRun encrypts the value with AES-256-GCM and stores only the ciphertext.
In job headers, you reference the secret as secret://name.
At execution time, TrigRun decrypts and substitutes the value before making the HTTP request.
Secret values are never returned by the API — only names and metadata are visible.

Creating a secret

curl -X POST https://api.trigrun.com/v1/secrets \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "stripe-key",
    "value": "sk_live_abc123..."
  }'

{
  "id": "clx...",
  "name": "stripe-key",
  "environment": "workspace",
  "created_at": "2026-03-15T10:00:00.000Z",
  "key_version": "v1"
}

Notice the response does not include the value. Once stored, secret values cannot be retrieved — only replaced by creating a new secret with the same name.

Using secrets in job headers

Reference secrets with secret:// syntax:

curl -X POST https://api.trigrun.com/v1/jobs \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "stripe-sync",
    "kind": "recurring",
    "schedule": { "every_n_minutes": 60 },
    "request": {
      "url": "https://api.stripe.com/v1/charges",
      "method": "GET",
      "headers": {
        "Authorization": "Bearer secret://stripe-key"
      }
    }
  }'

At execution time, secret://stripe-key is replaced with the decrypted value of the stripe-key secret.

You can use multiple secrets in the same job:

{
  "headers": {
    "Authorization": "Bearer secret://api-token",
    "X-Webhook-Secret": "secret://webhook-hmac"
  }
}

Listing secrets

curl https://api.trigrun.com/v1/secrets \
  -H "Authorization: Bearer $TOKEN"

{
  "items": [
    {
      "id": "clx...",
      "name": "stripe-key",
      "environment": "workspace",
      "created_at": "2026-03-15T10:00:00.000Z",
      "key_version": "v1"
    }
  ]
}

Values are never returned. You see only the name, environment, and creation time.

Updating a secret

To update a secret's value, delete the old one and create a new one with the same name. Secret names are unique within a workspace.

# Delete old
curl -X DELETE https://api.trigrun.com/v1/secrets/SECRET_ID \
  -H "Authorization: Bearer $TOKEN"

# Create with same name, new value
curl -X POST https://api.trigrun.com/v1/secrets \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "stripe-key",
    "value": "sk_live_new_value..."
  }'

Jobs referencing secret://stripe-key will use the new value on their next execution.

Deleting a secret

curl -X DELETE https://api.trigrun.com/v1/secrets/SECRET_ID \
  -H "Authorization: Bearer $TOKEN"

If a job references a deleted secret, the secret://name placeholder will not be resolved at execution time — the literal string secret://name will be sent as the header value. Make sure to update or pause affected jobs.

CLI reference

cronctl secrets list                                         # List all
cronctl secrets create --name api-key --value "sk_live_..."  # Create
cronctl secrets delete SECRET_ID                             # Delete