Docs menu

Keys, test and live

Every call to the API carries one of three credentials. Which one decides what the call may do.

Credential	Where it lives	What it can do
`hsk_test_...` / `hsk_live_...` secret key	Your server only	Register and remove agents, mint session tokens, read and act on incidents, read the event feed.
`hpk_test_...` / `hpk_live_...` publishable key	Your app	Says which organisation the app belongs to. Useless on its own.
`hst_...` session token	Your app, for one agent	Raise, update and close that agent's own SOS. Expires after an hour.

Send it as Authorization: Bearer <key>. The SDKs also send the publishable key with every agent call, and Hospify checks it belongs to the same organisation and mode as the session.

Test and live

Test and live are two separate worlds inside your organisation. Agents, incidents, events and webhooks made with test keys stay in test.

Test: available as soon as you sign in. The whole flow runs: incidents open, escalate, appear on the Live SOS Board marked as tests, send webhooks and fill the event feed. Nobody is alerted: no push, no SMS.
Live: real alerts to your supervisors and admins. Live keys can only be created once your business verification (KYB) is approved.

KYB first.Live keys and live webhooks are locked until Hospify approves your organisation. Upload your documents at org.hospify.cloud under Organisation, Verification. See Going live.

Rotating and revoking

Create as many keys as you need (one per environment or service) and revoke any of them in the dashboard. A revoked key stops working at once. A key is shown in full only when it's created: store it in your secrets manager.

Errors

Errors come back with a 4xx status and the same shape, so your code can switch on code:

{ "error": { "code": "kyb_required", "message": "Live keys need your business verification (KYB) approved." } }

Code	Status	Means
`invalid_key`	401	Missing, unknown or revoked key.
`wrong_key`	401	A publishable key where a secret key is needed, or the other way round.
`session_expired`	401	The agent's token ran out. The SDKs fetch a new one and retry.
`agent_inactive`	401 / 409	The agent was set inactive or removed.
`kyb_required`	403	A live key before KYB is approved.
`suspended`	403	Hospify has suspended API access for your organisation.
`agent_not_found`, `incident_not_found`	404	No such agent or incident in this mode.
`incident_closed`	409	The SOS is already closed.
`invalid_request`	422	A field is missing or wrong; the message names it.