API keys and scopes
A key has full access, or a list of scopes picked when it's created on the dashboard's API keys page. Presets cover the usual jobs:
| Preset | Scopes | For |
|---|---|---|
| Deploy | flows:write, flows:read, agents:read, numbers:read | CI: hcc deploy --live, or hcc.flows.deploy, hcc.serve |
| Local dev | dev:connect, flows:write, flows:read, simulator:write | A test key for hcc dev, hcc deploy and hcc.simulator |
| Read only | Every :read scope | Reports and dashboards of your own |
Tool sync needs nothing beyond flows:write: it runs on our side after a deploy. Pointing a number at a flow (hcc.numbers.update) needs numbers:write, which Deploy doesn't include: it takes a key an owner or admin makes.
A missing scope is an HccApiError that names it:
await hcc.numbers.release('num_1');
// HccApiError: status 403, code 'forbidden', "This API key is missing the numbers:write scope"The API's OpenAPI document gives each operation's scope as x-hcc-scope. Scopes and live/test are independent: a test key with the right scope still gets live_mode_only on what changes production. Scopes can't be edited: create a new key and revoke the old one.