CognitoUser Decorators

After authentication passes, you usually want to access user data. These decorators extract that data from the JWT token.

Three decorators

@CognitoUser: Works with both access and ID tokens.

@CognitoAccessUser: Only access tokens. Throws an error if you send an ID token.

@CognitoIdUser: Only ID tokens. Throws an error if you send an access token.

Get the full token

import { Authentication, CognitoUser } from '@nestjs-cognito/auth';
import type { CognitoJwtPayload } from "@nestjs-cognito/core";

@Controller('user')
export class UserController {
  @Get('profile')
  @Authentication()
  getProfile(@CognitoUser() user: CognitoJwtPayload) {
    return user;
  }
}

Get specific token types

For access tokens:

import { Authentication, CognitoAccessUser } from '@nestjs-cognito/auth';
import type { CognitoAccessTokenPayload } from "@nestjs-cognito/core";

@Controller('api')
export class ApiController {
  @Get('scope')
  @Authentication()
  getScope(@CognitoAccessUser() user: CognitoAccessTokenPayload) {
    return { scope: user.scope, username: user.username };
  }
}

For ID tokens:

import { Authentication, CognitoIdUser } from '@nestjs-cognito/auth';
import type { CognitoIdTokenPayload } from "@nestjs-cognito/core";

@Controller('user')
export class UserController {
  @Get('profile')
  @Authentication()
  getProfile(@CognitoIdUser() user: CognitoIdTokenPayload) {
    return {
      username: user['cognito:username'],
      email: user.email,
      groups: user['cognito:groups']
    };
  }
}

Get a single property

@Controller('user')
export class UserController {
  @Get('email')
  @Authentication()
  getEmail(@CognitoIdUser('email') email: string) {
    return { email };
  }

  @Get('scope')
  @Authentication()
  getScope(@CognitoAccessUser('scope') scope: string) {
    return { scope };
  }
}

Properties with cognito: prefix work both ways. You can request 'username' and it will find 'cognito:username'.

Get multiple properties

@Controller('user')
export class UserController {
  @Get('details')
  @Authentication()
  getDetails(@CognitoIdUser(['username', 'email', 'groups']) user) {
    return user; // Returns object with only selected properties
  }

  @Get('token-info')
  @Authentication()
  getTokenInfo(@CognitoAccessUser(['username', 'scope', 'client_id']) info) {
    return info;
  }
}

What's in each token

Access tokens contain: sub, username, client_id, scope, token_use, auth_time, iat, exp.

ID tokens contain: sub, cognito:username, email, email_verified, cognito:groups, phone_number, phone_number_verified, and any custom attributes you defined in your user pool.

Check token type manually

If you're using @CognitoUser and need to check which type you got:

import { isAccessTokenPayload, isIdTokenPayload } from '@nestjs-cognito/core';

@Get('token-type')
@Authentication()
checkTokenType(@CognitoUser() payload: CognitoJwtPayload) {
  if (isAccessTokenPayload(payload)) {
    return { type: 'access', scope: payload.scope };
  }

  if (isIdTokenPayload(payload)) {
    return { type: 'id', email: payload.email };
  }
}

Authentication Required: Always use @Authentication() or @Authorization() decorators before using any @Cognito*User decorator.