API Keys
API keys authenticate SDK clients, agents, workers, and protected operator tooling.
Key format
HaltState API keys use the hs_ prefix. Treat them as secrets. They belong in environment variables, a secrets manager, or protected operator configuration, never in browser JavaScript or public Proof Pack fields.
Generate and rotate
- Log in to the HaltState dashboard.
- Open Settings and API Keys.
- Create a key for the environment and agent or service that needs it.
- Copy it once, store it securely, and rotate it after staff changes, incidents, or accidental exposure.
Scopes and separation
| Scope | Typical permission |
|---|---|
agent:check | Call guard or check endpoints. |
agent:report | Report action outcomes after execution. |
admin:read | Read policies, approvals, and logs in protected tooling. |
admin:write | Modify policies and operator settings. |
Use separate keys for development, staging, production, and high-risk workers. A refund worker key should not also administer policy.
Implementation notes
Keep the HaltState call as close as possible to the side effect. The agent may plan and draft freely, but the wrapper around the actual action should be the place where authority is checked. That wrapper should send only the context required for policy evaluation: safe identifiers, normalized amounts, action names, risk flags, schedule windows, and redaction status. Raw customer payloads and secrets should stay in the business system or protected operator tooling.
Operational evidence
For each action, preserve the decision, the worker outcome, the idempotency key, safe resource references, latency, proof status, and redaction status. This evidence supports incident response and control narratives because it shows what the system did at runtime rather than only describing what the policy document intended. HaltState supports alignment work; it is not a substitute for legal advice or a compliance certification.