How to Use @Headers Decorator in NestJS Controllers

In NestJS, use the @Headers decorator inside a controller method to access HTTP request headers. You can get all headers as an object or a specific header by passing its name as a string to @Headers('header-name'). This helps you read client-sent data like tokens or content types.

Syntax

The @Headers decorator is used in a controller method parameter to access HTTP headers from the incoming request.

• @Headers() without arguments injects all headers as an object.
• @Headers('header-name') injects the value of a specific header.

This decorator works only in methods decorated with HTTP method decorators like @Get(), @Post(), etc.

typescript

import { Controller, Get, Headers } from '@nestjs/common';

@Controller('example')
export class ExampleController {
  @Get()
  getAllHeaders(@Headers() headers: Record<string, string>) {
    return headers;
  }

  @Get('specific')
  getSpecificHeader(@Headers('user-agent') userAgent: string) {
    return userAgent;
  }
}

Example

This example shows a NestJS controller with two routes: one returns all headers as an object, and the other returns the value of the User-Agent header.

typescript

import { Controller, Get, Headers } from '@nestjs/common';

@Controller('headers')
export class HeadersController {
  @Get()
  getHeaders(@Headers() headers: Record<string, string>) {
    return {
      message: 'All headers received',
      headers,
    };
  }

  @Get('user-agent')
  getUserAgent(@Headers('user-agent') userAgent: string) {
    return {
      message: 'User-Agent header received',
      userAgent,
    };
  }
}

Output

{
  "message": "User-Agent header received",
  "userAgent": "Mozilla/5.0 (example)"
}

Common Pitfalls

• Trying to use @Headers outside of a controller method parameter will not work.
• Header names are case-insensitive but should be passed in lowercase or as sent by the client.
• Accessing a header that does not exist returns undefined, so always check before using.
• Do not confuse @Headers with @Req() which gives the full request object.

typescript

import { Controller, Get, Headers } from '@nestjs/common';

@Controller('test')
export class TestController {
  // Wrong: Using @Headers outside method parameter
  // @Headers() headers: any; // This will cause an error

  @Get()
  getHeader(@Headers('authorization') auth: string) {
    if (!auth) {
      return { error: 'Authorization header missing' };
    }
    return { auth };
  }
}

Quick Reference

Usage	Description	Example
@Headers()	Injects all headers as an object	@Headers() headers: Record
@Headers('header-name')	Injects a specific header value	@Headers('content-type') contentType: string
Case sensitivity	Header names are case-insensitive but use lowercase	@Headers('authorization')
Return value if missing	Returns undefined if header not present	Check before use

Key Takeaways

Use @Headers() to get all HTTP headers as an object in a controller method.

Use @Headers('header-name') to get a specific header value by name.

Header names are case-insensitive but pass them in lowercase for consistency.

Always check if a header exists before using its value to avoid errors.

@Headers works only as a parameter decorator inside controller methods.