[sre-helmcode]

What

Docs for the NaN community write API (spec: helmcode/nan-devops AGENT-AUTOMATIONS-PHASE3-WRITE-API.md; backend: helmcode/nan-cloud-api#348, 0.8.261; CLI: nan-cli 0.1.33). EN + ES.

• /docs/automations: new section "Manage them from the CLI or the API" (secrets, automations and triggers from the CLI with YAML/JSON files, the API with Idempotency-Key, one-time webhook URL and signing secret, Cache-Control: no-store), who can write (CLI session, tokens with automations:write / secrets:write; never sk- or workspace keys, 403 credential_not_allowed), the warning (a write credential is as powerful as your secrets; never nan auth login inside a workspace; least scopes), updated_by / Last changed from, the rollout answers (CLI exit 64, 403 browser_session_required, 404 on /v1/secrets). Tokens table gains the three scopes, independence of scopes, browser-only minting and a warning callout. Limits table gains the write rate limits. "Why some actions need the browser" and the FAQ rewritten: approving and minting write-scoped tokens stay browser-only.
• /docs/webhooks: triggers from the CLI/API, URL and secret shown once (triggers add, triggers rotate with --url/--secret/--no-grace).
• /docs/nan-cli: the v0.1.33 write commands.
• /docs/runs: provider keys can be saved with nan secrets set; the "needs the browser" note removed.
• API reference (src/data/openapi.json): new Secrets tag and /v1/secrets routes (list, get, create with Idempotency-Key 201/200 replay, PATCH, PUT value, DELETE 204, secret_in_use / secrets_too_large with error.automations); automation writes (POST, PATCH, DELETE) and trigger writes (POST, PATCH, rotate, DELETE) with TriggerCreated / TriggerRotated one-time answers; updated_by on Secret, Automation and Trigger; new cliSession security scheme; scopes, credential_not_allowed, updated browser_session_required message, 429 rate_limited with the per-member budgets (secrets 30/120 per hour shared with the portal; automations 30/300 per hour).

Every shape was checked against cloud-api origin/main 95414e4 (handlers/account_secrets.go, automations.go, automation_triggers.go, middleware/write_credential.go, secrets/api.go, automations/api.go). The JSON was re-serialised by a script, so integer response keys are now in ascending order (no semantic change).

Tests

• New src/lib/openapiWriteApi.test.ts: every write operation's tag, security, scope wording, 401/403 bodies (exact token_scope_denied and credential_not_allowed messages), 429 on writes only, Secret/request schemas in handler field order, no value field, Idempotency-Key, 409s, no-store, trigger one-time answers, golden files, every example validated against its schema, reference text, no em-dashes.
• Updated openapiAutomations, openapiByok, openapiRuns, openapiSpec (surface list) and automationsDocs (commands, never a value on the command line, warning, rollout, rate limits, scopes, EN/ES parity).
• Golden fixtures refreshed from cloud-api (automations and triggers with updated_by, new trigger_rotate.json).
• npm test: 2311 passed. npm run build: OK.

Deploy

Merge after all of: WRITE_API_ENABLED flips to true in prod, nan-cli 0.1.33 is released (helmcode/nan-cli#53), and cloud-ui with the write scopes and Last changed from is deployed (helmcode/nan-cloud-ui#160). The pages describe the write API as rolling out per account, but the commands and portal labels must exist first.

Review follow-ups: Stripe triggers from the CLI (--signing-secret-file/--signing-secret-stdin on rotate, signing_secret in the add file), the write commands' credential order (--token-file, session, NAN_TOKEN, saved token), realistic examples (nan_whsec_, trigger 404 message, secrets newest first), browser_session_required on automation writes, API keys never on Secrets.

🤖 Generated with Claude Code