Authentication

Every /v1/shriek/ call sends Authorization: Bearer <token>. The token says who you are, and Shriek looks up which tenant you belong to. Credentials carry no scopes: anyone in a tenant can read and change all of that tenant’s data.

The two credentials

Credential	Who holds it	Acts as
ChirpAuth machine token	Your service	A member of the tenant its ChirpAuth client is connected to
ChirpAuth sign-in	A person, through the Shriek Android app	A member of the tenant they were added to

ChirpAuth machine token

Authorization: Bearer <ChirpAuth machine token>
Content-Type: application/json

Your service gets the token from ChirpAuth with the client-credentials grant, using its own ChirpAuth client id and secret.
Shriek accepts it only after Stackwell has connected your ChirpAuth client to your tenant. Each client belongs to one tenant.
A token from a client that isn’t connected to a tenant returns 403.

A ChirpAuth ID token issued to the Shriek Android app. Tokens issued to other ChirpAuth apps are refused. A person must also be added to a tenant by Stackwell; until then their calls return 403. Your service does not use this credential; it is listed so you know that the people in your tenant can do everything your service can.

What each credential allows

Both credentials have the same rights inside their own tenant:

Action	Allowed
Post alerts, heartbeats, incidents, public components and updates	Yes
Register and retire sources	Yes
Read the feed, threads, board, sources, incidents, public components	Yes
Anything in another tenant	No: every call is limited to the caller’s tenant

There is no read-only credential yet.

No credential

These need no Authorization header:

Path	What it is
`GET /health`	Liveness
`GET /public/{tenant}`	A tenant’s public status page (HTML)
`GET /public/{tenant}/board`	The public board, as JSON
`GET /public/{tenant}/{service}/updates`	A service’s public updates, as JSON

curl -sS https://shriek.dev/v1/shriek/board | grep -Fx '{"error":"unauthorized"}'

Endpoints the Android app uses

These exist for the Shriek Android app. Your service does not need them.

Endpoint	What it does
`GET /v1/shriek/whoami`	Tells a signed-in person their ChirpAuth id and whether they belong to a tenant yet
`POST /v1/shriek/devices`	Registers a phone to receive the tenant’s notifications
`PUT /v1/shriek/devices`	Moves a phone’s registration to the new push token Android gave it, in the same tenant. It needs no `Authorization` header: the random leave key the phone got when it registered is the credential
`DELETE /v1/shriek/devices`	Stops the tenant’s notifications to a phone, when its person signs out or switches account. It needs no `Authorization` header: the random leave key the phone got when it registered is the credential
`POST /v1/shriek/receipts`	Reports that a notification was shown; see Phone notifications

Keyboard shortcuts