Authentication
The Sentinel API is JSON over HTTPS, versioned under /v1. The OpenAPI 3.1 file that ships with each release (api/openapi.yaml) is the source of truth; these pages are written from it.
Base URL
Your install serves the API on your own network, so the base URL is whatever host you run it on. A local install listens on http://localhost:8080.
https://sentinel.internal.example.com/v1/...
The same server also serves the dashboard at /. The API doesn't need to be exposed to the public internet. Your payment services call it over your internal network.
API keys
Send a key as a bearer token on every /v1 request. /healthz is the only route that doesn't need one.
POST /v1/events?mode=sync HTTP/1.1
Host: sentinel.internal.example.com
Authorization: Bearer snt_live_...
Content-Type: application/json
- Keys start with
snt_live_. The rest is 32 random bytes, URL-safe base64. - Each key is shown once, when it's created. Only a SHA-256 hash is stored, so a lost key can't be recovered. Create a new one.
- Each key belongs to one organisation, and every request is scoped to it. You only ever see records in your own organisation.
- Keys are checked against your install's own database. Somu Labs never sees them.
- Revoking a key takes effect on the next request. Revoked keys stay listed for the audit trail.
- The key making a request is its actor. Notes, closure requests, approvals and rule changes record the key's ID, and four-eyes checks compare key IDs.
Creating keys
There are three ways to get a key.
| Where | How | Use it for |
|---|---|---|
| Dashboard | Developers → API keys → Create key | Day-to-day, once you can sign in |
| API | POST /v1/keys | Automation |
| Command line | sentinel-admin key create -org <org> -name <name> | Any time you have database access, including a fresh install |
The command line tool reads SENTINEL_DATABASE_URL and prints the new key once:
go run ./cmd/sentinel-admin key create -name dev
In the container image it's /app/sentinel-admin. The -org flag defaults to default.
The first key on a fresh install
A new install has no keys, so nothing can call the API or sign in to the dashboard. Either run sentinel-admin key create once, or set a bootstrap key before the first start:
| Variable | Default | Meaning |
|---|---|---|
SENTINEL_BOOTSTRAP_API_KEY | unset | Stored as the organisation's first key, named bootstrap, but only while the organisation has no active key |
SENTINEL_BOOTSTRAP_ORG | default | The organisation the bootstrap key belongs to |
The value must start with snt_live_ and be at least 40 characters long. One way to make one:
echo snt_live_$(openssl rand -hex 24)
Once the organisation has an active key, the setting does nothing, so leaving it in place is harmless and a revoked bootstrap key is never brought back. Still, create your own keys, revoke the bootstrap one, and remove the variable.
Failed authentication
A missing, invalid or revoked key returns 401:
{
"error": "missing or invalid API key"
}