Smirkly Auth

Authentication, sessions, token rotation, and verification flows.

This service owns user sign-up, sign-in, email verification, JWT access tokens, refresh-token rotation, session revocation, logout, and password changes.

Open API Reference Run Locally Read Architecture

Production Docs Map

Configure

Runtime files, SMTP settings, JWT keys, proxy trust, and secret rules.

Open Configuration

Deploy

Build gates, migrations, prod static config, rollout order, and rollback guidance.

Open Deployment

Operate

SMTP delivery checks, resend commands, local resets, and incident first checks.

Open Runbooks

Service Surface

Identity

User registration supports username plus email or phone. Passwords are validated before hashing and persistence.

Sessions

Sign-in creates a device and session record. Access-token authentication is checked against active session state in Postgres.

Refresh Rotation

Refresh tokens are stored as hashes, rotated on refresh, and protected by token family reuse detection.

Primary Endpoints

Method Path Purpose
POST /auth/v0/sign-up Create a new user and enqueue email verification when email is present.
POST /auth/v0/verify-email Verify an email address with the latest active code.
POST /auth/v0/verify-email/resend Queue a fresh verification code for an unverified email address.
POST /auth/v0/sign-in Create a session, return an access token, and set the refresh cookie.
POST /auth/v0/refresh Rotate the refresh token and return a new access token.
POST /auth/v0/logout Revoke the current session and clear the refresh cookie.
POST /auth/v0/change-password Update the password and revoke all user sessions.
GET /auth/v0/.well-known/jwks.json Expose the public JWKS used by other services to verify access tokens.

Repository Map

src/auth/api/v0/handlers       HTTP handlers
src/auth/services/usecases     Application use cases
src/auth/services/ports        Interfaces for infra dependencies
src/auth/infra                 Postgres, SMTP, JWT, bcrypt, id providers
src/auth/domain                Domain models and value objects
sql/auth                       SQL query files compiled by userver
migrations                     Postgres schema migrations
openapi/auth-v0.yaml           OpenAPI contract