#Authentication Overview

tsdevstack provides a complete authentication system out of the box, handling JWT tokens, session management, and protected routes.

#How authentication works

The diagram below shows the authentication flow (not the full infrastructure - production deployments include load balancers, WAF, etc.):

                        Browser
                           |
                           v
+--------------------------------------------------+
|                   Kong Gateway                    |
|  - Validates JWT tokens                          |
|  - Extracts user info for backend services       |
+--------------------------------------------------+
                           |
              +------------+------------+
              |                         |
              v                         v
      +---------------+         +---------------+
      |  Auth Service |         | Other Service |
      |  (issues JWT) |         | (trusts Kong) |
      +---------------+         +---------------+

Kong validates tokens at the gateway level before requests reach your services.

#Key concepts

#JWT tokens

tsdevstack uses JSON Web Tokens for stateless authentication:

• Access tokens - Short-lived tokens for API requests
• Refresh tokens - Longer-lived tokens for obtaining new access tokens

Token lifetimes are configurable via environment variables. See JWT Tokens for details.

#Two-layer authentication

Authentication works at two independent layers, controlled by different decorators:

Important: Without @ApiBearerAuth(), Kong treats the route as public (no JWT required). But AuthGuard still rejects anonymous callers unless you also add @Public().

For fully public endpoints (login, signup): use @Public() and omit @ApiBearerAuth().

#Protected routes

By default, all endpoints require authentication (AuthGuard is global). Mark public endpoints explicitly:

import { Controller, Get, Req } from '@nestjs/common';
import { Public } from '@tsdevstack/nest-common';
import type { AuthenticatedRequest } from '@tsdevstack/nest-common';

@Controller('users')
export class UsersController {
  @Get('profile')
  getProfile(@Req() req: AuthenticatedRequest) {
    // req.user contains JWT claims
    return { id: req.user.id, email: req.user.email };
  }

  @Get('public-data')
  @Public()
  getPublicData() {
    // No authentication required
    return { message: 'public' };
  }
}

See Protected Routes for more patterns.

#Roles

Every user has a system role (USER or ADMIN) and optional custom roles, carried in the token. Restrict endpoints with @Roles(); see Roles. How to create the first admin and manage users locally and in the cloud: Managing Users.

#API keys

For machine access without a user login, mark endpoints @PartnerApi() and issue API keys to named consumers through the auth-service admin API. The gateway checks keys, expiry and per-key limits on every request. See API Keys.

#Security standards

The auth service template follows OWASP security guidelines for authentication, session management, and cryptographic storage. See JWT Tokens for the full mapping, and Compliance Readiness for infrastructure-level controls.

#Quick start

1. Authentication is enabled by default (AuthGuard is global)
2. Kong validates tokens for routes with @ApiBearerAuth()
3. Use @Public() to skip authentication for specific endpoints
4. Access user info via @Req() req: AuthenticatedRequest and req.user