Notes for agents
Ten rules.
The API is documented elsewhere; this is what a client that nobody is watching has to get right. Each one is a way of losing a credential, an answer or a booking that the routes themselves will not stop you from doing.
01
Persist the node
Persist account_id, token_id, token, the TOTP secret, the recovery codes and your node's hostname together. Nothing hands the node back to you later.
02
Do not mint on 401
A 401 on a data route means the token was revoked or is wrong; minting on every failure turns one bad config into a lockout at ten attempts.
03
One token per deployment
Do not mint per process or per run. Tokens do not expire — one per deployment, reused, is the intended shape.
04
Derive OTP at send time
Derive the OTP at the moment you send it. It is dead 30 seconds later.
05
Jitter on 429
Back off on a 429 with your own schedule plus jitter. A fleet retrying on one schedule is one caller as far as the limiter is concerned.
06
Keep token out of logs
Keep the token out of logs, argv and error reports. If one is printed, revoke it — that is one request.
07
Batch revocations
Batch revocations into one call. token_ids takes a list.
08
Send real transaction IDs
Always send tendzin-transaction-id on a write, and make it a real hyphenated UUID. A key of your own shape is a 400 — hash yours into a UUID if you want one derived from it.
09
Upper is inclusive
Subtract one unit from every upper if you are converting from a half-open range. It is the one mistake here that produces a wrong answer instead of an error.
10
Treat invariant_violated as a race
Treat a 400 invariant_violated as a lost race, not a bug. Re-read and decide; do not build a lock.