Authentication

The API accepts two kinds of credential. Machines use API keys. People using the dashboard use a session.

API keys

Send a key as a bearer token on every request:

curl https://api.sandbox.halvorai.com/v1/events \
  -H "Authorization: Bearer $HALVOR_API_KEY"

A key looks like hk_test_ or hk_live_ followed by 32 random letters and digits. The prefix says which environment it belongs to. HalvorAI stores only a SHA-256 hash and the first twelve characters, so the full key is shown once, when you create it. Lose it and you create a new one.

Scopes

A key can do only what its scopes allow. Give each key the least it needs.

Scope	Allows
events:write	Send events, validate events, register sources. The default for an ingest key.
events:read	List and read events, including evidence values.
agents:read	Read agents, owners and payees.
alerts:read, alerts:write	Read alerts and screenings. Act on alerts and review screening matches.
cases:read, cases:write	Read cases. Create and change cases.
packs:write	Build evidence packs and reports, and share them.
screening:write	Screen a payee on demand with POST /v1/screen.

A request outside the key’s scopes gets 403 with the code forbidden.

Create and revoke keys

Create keys in the dashboard under Developers, or with POST /v1/api-keys while signed in. Creating and revoking keys needs a signed-in user, not another key, so a leaked ingest key cannot mint more keys. Developers can manage test keys. Only admins and owners can manage live keys.

DELETE /v1/api-keys/{id} revokes a key. It stops working at once on the instance that handled the revoke and everywhere within 30 seconds.

Rotate a key without downtime

1. Create a new key with the same scopes.
2. Deploy it to your service.
3. Check that the old key’s last used time in the dashboard has stopped moving.
4. Revoke the old key.

Sessions

The dashboard signs people in with an emailed link, so there are no passwords. A session cookie is then sent with dashboard requests. Sessions act inside one organization, with one role. Owners and admins must also use a second factor on the live environment.

Some routes are for signed-in users only: creating and revoking keys, and labelling an agent.

Who am I

GET /v1/me returns the credential’s identity: for a key, its organization, environment and scopes; for a session, the user, organization and role. It is the quickest way to check that a key works.

curl https://api.sandbox.halvorai.com/v1/me -H "Authorization: Bearer $HALVOR_API_KEY"

Status codes

Status	Code	Meaning
401	unauthorized	No credential, or it is not valid or was revoked.
401	key_environment_mismatch	A test key against production, or a live key against sandbox.
403	forbidden	The credential is valid but the scope or role does not allow this.

Keep keys safe

• Never put a key in browser code, a mobile app or a public repository.
• Use one key per service and environment, so you can revoke one without touching the rest.
• The SDK redacts anything that looks like a HalvorAI key from text it sends.