collect_api_key

ch.zeno-works/zeno · Verify this server

Collect the key once the user has approved. `status` is one of: - `pending` — nobody has approved yet, or (with `throttled: true`) we were rate-limited and learned nothing. **Wait `poll_interval_seconds`, then call again** — every answer carries it. Do not ask the user to tell you when they are done: you cannot detect it any other way, and handing the wait back to the user is how these sessions die. - `ready` — `api_key` is the credential. **Follow the `note` that comes with it before anything else**: the key does nothing until the client's configuration holds it, and calling again issues nothing. `scope` says what it can reach (`onboarding`, `company` or `full`) and `company_id` which company, if any. **When `scope` is `onboarding` the user has no company yet and this key exists to make one: call `onboarding_guide` next** — it needs no key, so read it while the user installs this one. It is the only place that says which documents to ask them for, and asking for them all at once is the difference between one conversation and seven. - `collected` — this request already issued its key and nothing new was issued. Follow the `note`. - `denied` — **stop.** Do not start another request; a human refused it ("that was not me"). Raising a second one is how a refusal turns into a prompt the user has to refuse repeatedly. - `expired` — the request timed out. **Do not simply open another one**, and what to do depends on which door you opened, which only you know. `request_api_key`: ask whether they saw the approval page, and call it again if they want to retry. `start_signup`: they may have finished registering in the browser meanwhile, in which case they now HAVE an account and `request_api_key` is the path — ask. If they did not, tell them plainly that it timed out; starting another signup without asking is how a refusal turns into a prompt they have to refuse repeatedly. A `pending` answer is a success, not an error; it is deliberately not an error status, because an error would be read as "do not retry" and retrying is the entire protocol. A rate limit mid-wait is reported the same way, with `throttled: true` and a longer `poll_interval_seconds` — slow down, do not stop.