auth-server overview

auth-server is the Go HTTP API at the centre of the platform. It owns the database (Postgres), the cache (Redis), the JWT signing secrets, the SSO state store, the audit log, the m2m client registry. Every SDK in this directory is either a typed wrapper around its HTTP surface or a way to validate the JWTs it issues.

Live	new-auth.vendidit.com
Source	Vendidit/auth-server
Stack	Go 1.25 · stdlib net/http · Postgres 13+ · Redis 7+
Auth	HS256 JWTs · bcrypt cost 12 · OAuth 2.0 + PKCE
Status	Production.

📦

Every consumer needs to register an app first. A system_admin creates an apps row, the consumer sets VENDIDIT_APP_CODE + JWT_ACCESS_SECRET, and tokens issued to that app_code carry the right scope. See the full flow in App registration.

The 80% usage

You don’t typically call the auth-server directly — the SDKs do. The shortest path:

1. Register an app (App registration).
2. Pick the SDK for your runtime:
   • Browser: @vendidit/auth-client
   • NestJS: @vendidit/auth-server-nest
   • Node (other): @vendidit/auth-server-ts
   • Laravel: vendidit/auth-server-laravel
   • PHP (other): vendidit/auth-server-php
3. The SDK calls /auth/login, /auth/refresh, /auth/me, etc. for you. Local JWT validation uses the shared JWT_ACCESS_SECRET.

For direct HTTP integration, the full endpoint surface is documented in API endpoints.

What it does

• Authn: password, SSO (Google / Apple / Microsoft / GitHub) with PKCE, magic-link, TOTP 2FA.
• Session management: list + terminate; logout-all bumps a per-user token-version so every outstanding access token across replicas becomes invalid on the next request.
• Authz: roles (system_admin, super_admin, org_admin, …) + fine-grained resource:action permissions, scoped per-app or per-org.
• Refresh-token rotation with family-aware reuse detection (RFC 6819 §5.2.2.3).
• m2m client_credentials (POST /oauth/token) — issues service-principal JWTs (token_type: "service").
• Audit log — async writer; records login.success/failed, password.change/reset, logout.all, refresh.reuse_detected, etc.
• Cognito auto-migration — drop-in legacy bridge for cutover from AWS Cognito (off by default).

Deployment shape

• Stateless HTTP service — horizontally scalable, no sticky sessions.
• Postgres owns users / orgs / memberships / roles / permissions / refresh_tokens / sessions / m2m_clients.
• Redis is optional but recommended in prod — falls back to no-op + in-memory where possible. Without it: signature-only validation, no cross-replica token-version invalidation, in-memory SSO state (single-replica only).

Related pages

• How it works — architecture deep-dive.
• API endpoints — auto-generated reference.
• App registration — the onboarding step.
• Development — local setup, env vars, migrations, JWT-secret rotation runbook.