@TokenDelivery()

Package: @nauth-toolkit/nestjs Type: Method Decorator

Method decorator that overrides the global token delivery mode for a specific route.

Import from NestJS Package

import { TokenDelivery } from '@nauth-toolkit/nestjs';

Overview

The @TokenDelivery() decorator allows you to force a specific token delivery mode for an endpoint, regardless of the global configuration. This is useful when you need different delivery modes for different clients (web vs mobile).

Key Features:

• Override global token delivery mode per route
• Force cookie-based delivery for web endpoints
• Force JSON delivery for mobile/API endpoints
• Works with hybrid mode configuration

Usage

Force Cookie Delivery

Force cookie-based delivery for web endpoints:

import { Controller, Post, Body } from '@nestjs/common';
import { Public, TokenDelivery } from '@nauth-toolkit/nestjs';

@Controller('auth')
export class AuthController {
  @Public()
  @Post('login/web')
  @TokenDelivery('cookies')
  async loginWeb(@Body() dto: LoginDTO) {
    return this.authService.login(dto);
  }
}

Force JSON Delivery

Force JSON delivery for mobile/API endpoints:

import { Controller, Post, Body } from '@nestjs/common';
import { Public, TokenDelivery } from '@nauth-toolkit/nestjs';

@Controller('auth')
export class AuthController {
  @Public()
  @Post('login/mobile')
  @TokenDelivery('json')
  async loginMobile(@Body() dto: LoginDTO) {
    return this.authService.login(dto);
  }
}

Mixed Delivery Modes

Use different delivery modes for different endpoints:

import { Controller, Post, Get, UseGuards } from '@nestjs/common';
import { AuthGuard, TokenDelivery, CurrentUser } from '@nauth-toolkit/nestjs';
import type { IUser } from '@nauth-toolkit/nestjs';

@Controller('api')
@UseGuards(AuthGuard)
export class ApiController {
  @Get('web/data')
  @TokenDelivery('cookies')
  getWebData(@CurrentUser() user: IUser) {
    return { data: 'web data' };
  }

  @Get('mobile/data')
  @TokenDelivery('json')
  getMobileData(@CurrentUser() user: IUser) {
    return { data: 'mobile data' };
  }
}

Delivery Modes

'cookies'

Forces cookie-based token delivery:

• Tokens set as httpOnly cookies
• Tokens stripped from response body
• CSRF protection required
• Suitable for web applications

'json'

Forces JSON token delivery:

• Tokens returned in response body
• No cookies set
• CSRF protection not required
• Suitable for mobile/API clients

Configuration Validation

The decorator only sets route metadata. Validation against global configuration happens at request time inside TokenDeliveryHttpService, which is called by the response interceptor. If the route-level mode conflicts with global config, the interceptor throws an error:

// Global config: tokenDelivery.method = 'json'
@TokenDelivery('cookies') // COOKIES_NOT_ALLOWED thrown by interceptor at request time

// Global config: tokenDelivery.method = 'cookies'
@TokenDelivery('json') // BEARER_NOT_ALLOWED thrown by interceptor at request time

// Global config: tokenDelivery.method = 'hybrid'
@TokenDelivery('cookies') // Allowed
@TokenDelivery('json') // Allowed

Errors

These errors are thrown by the token delivery interceptor (not by the decorator itself).

Code	When	Details
COOKIES_NOT_ALLOWED	Route requests cookies but global config is 'json'	undefined
BEARER_NOT_ALLOWED	Route requests JSON but global config is 'cookies'	undefined

Related APIs

• AuthGuard - Route protection
• CsrfGuard - CSRF protection (required for cookies)
• @Public() Decorator - Mark routes as public
• Token Delivery - Token delivery modes guide