API-key auth
Apps with -auth jwt|both and -db set also get service-key auth, checking the X-Api-Secret header against a new core_services table. By default (without -merge-service-auth) this is middleware.RequireServiceAuth — a second, wholly separate auth wrapper for app-to-app calls, never falling back to/from RequireAuth: a route is either user-facing (RequireAuth) or service-only (RequireServiceAuth), so a service-only route can never accidentally accept an end-user JWT. The API key must never be embedded in any UI-facing code — treat it like a database credential.
core.CreateService(ctx, name) generates a random key, stores only its SHA-256 hash, and returns the plaintext key exactly once — it's never retrievable again. VerifyServiceKey/RevokeService/ListServices/GetService round out the set; on success, the calling service's name is attached via a new auth.ContextWithService/auth.Service(r) pair, kept as a distinct context key from the user Subject. A generated Swagger-documented admin API (/admin/services//admin/users) wraps these functions for you — see below.
Usage — a route meant to be called only by another backend service, never a browser:
mux.HandleFunc("POST /internal/sync", middleware.RequireServiceAuth(func(w http.ResponseWriter, r *http.Request) {
name, _ := auth.Service(r) // the calling service's core_services Name
// ...
}))A companion core_users table (core.GetUser/CreateUser/SetUserStatus/ListUsers) is a minimal local record, not a profile store: UserId is the same value as the JWT sub claim, plus Username/UserRole/UserType and a Status kill-switch. Real profile data (name, email, etc.) stays wherever it already lives.
-merge-service-auth is the opt-in alternative: instead of a separate RequireServiceAuth, the X-Api-Secret check is folded into RequireAuth itself, tried after JWT (and session, for -auth both) — so a service/automation caller can hit the exact same -protected routes a human user would, without a route needing a service-only variant of itself. A matching service key still attaches auth.ContextWithService, plus auth.ContextWithSubject set to the service's name, purely so subject-reading code has something to evaluate. Off by default: a pure API service that wants user-only and service-only routes to stay structurally distinct should leave this unset and keep the separate RequireServiceAuth. Retrofit an already-scaffolded app with nexler update -merge-service-auth (a separate, explicit opt-in step, never run automatically by a plain nexler update).
A service calling on someone's behalf. With either design, a service-key caller may send two more headers, handled in middleware/service_caller.go (serviceCallerContext):
X-Acting-Subject: the user the service is working for (e.g. who started a workflow run). It is read back withauth.ActingSubject(r)and written to the audit entry asacting_subject. It is informational only: permission checks still run against the service itself.X-Org-Id(with-multitenant): the tenant org the call is for, attached withauth.ContextWithOrg. It is honoured only for a service whosecore_servicesrecord hasacts_for_orgsset (core.SetServiceActsForOrgs, checked bycore.ServiceActsForOrgs); any other service sending it gets 403. The flag is Mongo core only for now; on a SQL core it is always off.