Authentication

HookSentry uses two independent authentication schemes, depending on which endpoint you call.

JWT bearer tokens

Call POST /api/v1/auth/login with an email and password to receive an accessToken (TTL 15 minutes) and a refreshToken (TTL 7 days, stored server-side in Redis). Send the access token on every subsequent request:

var request = new HttpRequestMessage(HttpMethod.Get, "https://api.hooksentry.com/api/v1/tenants/{id}");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", accessToken);

using var client = new HttpClient();
var response = await client.SendAsync(request);

When the access token expires, exchange the refresh token for a new pair via POST /api/v1/auth/refresh — the refresh token you send is consumed and a new one is issued (single-use). Call POST /api/v1/auth/logout to invalidate a refresh token and immediately revoke the access token, both before their natural expiry.

API keys (ingest only)

The ingest endpoint authenticates with an API key instead of a JWT, since the caller is typically a third-party service (GitHub, Stripe, your own backend) rather than a logged in dashboard user. Create a key via POST /api/v1/apikeys (JWT-authenticated), then send it on every ingest call:

X-Api-Key: <key>

The plain text key value is only ever returned once, at creation time — HookSentry stores just a hash. If you lose it, revoke it and create a new one.

Roles

Every user has one role, carried as a role claim in the JWT. Role checks always read the claim from the token — never from the request body — so a caller cannot escalate privileges by editing a payload.

The tenant's first user (created together with the tenant) is always an Owner.