Authentication

Every call except GET /health sends a ChirpAuth machine token:

Authorization: Bearer <ChirpAuth machine token>

Getting a token

Your database’s clients are ChirpAuth confidential clients. Exchange a client’s id and secret for a token with the client_credentials grant:

curl -sS https://signin.chirpauth.com/token \
  -d grant_type=client_credentials \
  -d client_id="$RELSTORE_CLIENT_ID" \
  -d client_secret="$RELSTORE_CLIENT_SECRET"

Use the response’s id_token. Tokens expire; mint a new one when yours does.

relstore accepts a token only if:

• ChirpAuth signed it and it has not expired;
• it is a machine token, not a person’s sign-in token;
• its client is bound to a database on relstore.

Anything else gets 403 with the body forbidden, whatever the reason.

What each client may do

The client the token belongs to decides the database and the role:

Every route acts on the client’s own database only. The purge and erasure routes are not enabled yet; see Concepts.

Keep the agent client’s secret on your server. Anyone holding it can write to your database (though not rewrite or remove its history).

Use each client for relstore only

Send a client’s tokens to relstore and to nothing else. A ChirpAuth machine token is not tied to the service it is sent to, so any service that receives one of your tokens could use it at relstore until it expires (up to an hour). For the same reason, don’t use a client you already use with another service: ask Stackwell for a new pair instead. relstore cannot check this, so it is yours to keep.

Not yet: tokens that only relstore accepts.

No credential

Only GET /health works without a token:

curl -fsS https://relstore.stackwell.tech/health

Any other route answers 403:

curl -sS https://relstore.stackwell.tech/v1/purge-requests | grep -Fx forbidden

A request whose body can’t be parsed is refused before its token is checked, so it gets the parsing error (400, 413, 415 or 422) rather than 403. See Errors and limits.