Good practices
- Least privilege: ask for the fewest scopes the task needs (
metrics:read for reports; broadcasts:write + flows:read to send). write already implies read.
- One token per account and per purpose, with
expiresAt. Revoke it when the task ends.
- Start every session with
GET /v1/me; pass accountId explicitly whenever the credential reaches more than one account.
- Treat the token as a password: never print it, log it, put it in a URL or send it to a third party. It starts with
cf_live_ so secret scanners can flag leaks; if one leaks, the owner revokes it at once in Settings, API tokens.
- Confirm with the human before any write that reaches leads (broadcasts, journeys activation, flow publication). Prefer scheduling over
isImmediate so the human can cancel (POST /v1/broadcasts/{broadcastId}/cancel).
- Read before you write:
PUT endpoints replace the whole resource; PATCH changes only what you send, and null clears.
- Walk lists with
nextCursor until it is null; do not build cursors yourself.
- Respect
429 and Retry-After; spread polling (a broadcast status every 30 to 60 seconds is enough).
- Enums are integers; dates are UTC except
scheduledTo (page local).