Cron Secrets
Store sensitive values like API tokens and passwords securely, then reference them in cron job
templates using {{secret.KEY_NAME}} syntax.
How It Works
- Create a secret with a key and value via the API or dashboard
- The value is encrypted with AES-256 and stored securely
- Reference the secret in cron job commands or request bodies using
{{secret.KEY_NAME}} - At execution time, the CLI agent decrypts and substitutes the value
Security
Secret values are never returned in API responses. They are encrypted at rest with AES-256 and only decrypted at execution time by the CLI agent.
Template Variables
Secrets are referenced using the {{secret.KEY}} syntax. These are resolved at execution
time alongside other built-in variables:
| Variable | Example Value | Description |
|---|---|---|
{{secret.KEY}} | (decrypted value) | Your stored secret |
{{now}} | 2026-03-09T15:00:00Z | Current UTC timestamp |
{{now_unix}} | 1772560800 | Current Unix timestamp |
{{last_run}} | 2026-03-09T14:00:00Z | Previous execution time |
{{job_name}} | daily-report | Current job name |
{{job_id}} | cj_abc123 | Current job ID |
{{execution_id}} | exec_xyz789 | Current execution ID |
{{random_uuid}} | 550e8400-e29b-... | New UUID per execution |
Example Usage
Base URL
https://api.hookwatch.dev/v1/cron-secretsThe Secret Object
The secret value is never included in API responses. Only the key and metadata are returned.
Properties
| Field | Type | Description |
|---|---|---|
id | string | Unique identifier |
user_id | string | Owner user ID |
team_id | string | Team ID (if team-scoped) |
key | string | Secret key name (unique per user, e.g., API_TOKEN) |
created_at | string | ISO 8601 creation timestamp |
updated_at | string | ISO 8601 last update timestamp |
Create Secret
Store a new encrypted secret.
POST /v1/cron-secretsRequest Body
| Field | Type | Required | Description |
|---|---|---|---|
key | string | Yes | Secret key name (must be unique per user) |
value | string | Yes | Secret value (encrypted at rest with AES-256) |
Example
Unique Keys
Each user can only have one secret per key name. Attempting to create a duplicate returns 409 Conflict.
List Secrets
Retrieve all secrets for the authenticated user. Values are not included.
GET /v1/cron-secretsResponse
Update Secret
Update the value of an existing secret. The key is immutable.
PUT /v1/cron-secrets/:idRequest Body
| Field | Type | Required | Description |
|---|---|---|---|
value | string | Yes | New secret value (re-encrypted at rest) |
Delete Secret
Permanently delete a secret.
DELETE /v1/cron-secrets/:idWarning
Any cron jobs referencing this secret via {{secret.KEY}} will fail to resolve
the variable at execution time.
Error Codes
| Status | Error | Description |
|---|---|---|
400 | Bad Request | Missing key or value |
401 | Unauthorized | Invalid or missing access token |
404 | Not Found | Secret not found or access denied |
409 | Conflict | A secret with this key already exists |