Skip to main content
current (v21)

API Reference

CatbeeJwtService​

The main service for JWT operations.

Service Aliases
import { CatbeeJwtService } from '@ng-catbee/jwt';

You can also import the service using the shorter alias:

import { JwtService } from '@ng-catbee/jwt';

Both CatbeeJwtService and JwtService refer to the same service.

API Summary​

Types​

JwtPayload​

Standard JWT payload interface.

interface JwtPayload {
  iss?: string;  // Issuer
  sub?: string;  // Subject
  aud?: string | string[];  // Audience
  exp?: number;  // Expiration time (seconds since epoch)
  nbf?: number;  // Not before (seconds since epoch)
  iat?: number;  // Issued at (seconds since epoch)
  jti?: string;  // JWT ID
  [key: string]: any;  // Custom claims
}

DecodedJwt<T>​

Complete decoded JWT structure.

export interface DecodedJwt<T = JwtPayload> {
  /** JWT header containing algorithm and token type */
  header: {
    alg: string;
    typ: string;
    [key: string]: any;
  };
  payload: T; // Decoded payload of type T
  signature: string; // Signature part of the JWT
  raw: string; // Original JWT string
}

Methods​

decodePayload()​

Decodes the JWT payload with type safety.

Method Signature:

decodePayload<T = JwtPayload>(token: string): T | null

Parameters:

  • token - The JWT token string

Returns: The decoded payload of type T, or null if decoding fails

Example:

interface UserPayload extends JwtPayload {
  userId: string;
  email: string;
}

const payload = jwtService.decodePayload<UserPayload>(token);
if (payload) {
  console.log(payload.email);
}

decode()​

Decodes the complete JWT including header, payload, and signature.

Method Signature:

decode<T = JwtPayload>(token: string): DecodedJwt<T> | null

Parameters:

  • token - The JWT token string

Returns: Object containing header, payload, and signature, or null if decoding fails

Example:

const decoded = jwtService.decode(token);
if (decoded) {
  console.log(decoded.header.alg);
  console.log(decoded.payload);
  console.log(decoded.signature);
}

isExpired()​

Checks if the token has expired.

Method Signature:

isExpired(token: string | JwtPayload, offsetSeconds: number = 0): boolean

Parameters:

  • token - The JWT token string
  • offsetSeconds - Optional offset in seconds to check expiration earlier (default: 0)

Returns: true if expired, false otherwise

Example:

// Check if token is expired
if (jwtService.isExpired(token)) {
  console.log('Token has expired');
}

// Check if token will expire in the next 60 seconds
if (jwtService.isExpired(token, 60)) {
  console.log('Token will expire soon');
}

isValidFormat()​

Validates the JWT format (must have 3 parts separated by dots).

Method Signature:

isValidFormat(token: string): boolean

Parameters:

  • token - The JWT token string

Returns: true if valid format, false otherwise

Example:

if (!jwtService.isValidFormat(token)) {
  console.error('Invalid JWT format');
}

getExpirationDate()​

Gets the expiration date from the token's exp claim.

Method Signature:

getExpirationDate(token: string | JwtPayload): Date | null

Parameters:

  • token - The JWT token string

Returns: Date object representing expiration time, or null if not found

Example:

const expDate = jwtService.getExpirationDate(token);
if (expDate) {
  console.log('Expires on:', expDate.toLocaleString());
}

getIssuedDate()​

Gets the issued-at date from the token's iat claim.

Method Signature:

getIssuedDate(token: string | JwtPayload): Date | null

Parameters:

  • token - The JWT token string

Returns: Date object representing issued time, or null if not found

Example:

const issuedDate = jwtService.getIssuedDate(token);
if (issuedDate) {
  console.log('Issued at:', issuedDate.toLocaleString());
}

getRemainingTime()​

Gets the remaining time in seconds until the token expires.

Method Signature:

getRemainingTime(token: string | JwtPayload): number | null

Parameters:

  • token - The JWT token string

Returns: Number of seconds until expiration, or null if no expiration claim

Example:

const remaining = jwtService.getRemainingTime(token);
if (remaining !== null) {
  console.log(`Token expires in ${remaining} seconds`);
}

watchExpiry()​

Returns an observable that emits the remaining time until expiration at specified intervals.

Method Signature:

watchExpiry(token: string, tickMs: number = 1000): Observable<number>

Parameters:

  • token - The JWT token string
  • tickMs - Interval in milliseconds to emit updates (default: 1000)

Returns: Observable that emits remaining seconds

Example:

jwtService.watchExpiry(token, 1000)
  .pipe(takeUntil(destroy$))
  .subscribe(remaining => {
    console.log(`${remaining}s remaining`);
    if (remaining <= 0) {
      // Token expired - logout user
    }
  });

getClaim()​

Extracts a specific claim from the token payload with type safety.

Method Signature:

getClaim<T>(token: string, claim: string): T | null

Parameters:

  • token - The JWT token string
  • claim - The claim name to extract

Returns: The claim value of type T, or null if not found

Example:

const role = jwtService.getClaim<string>(token, 'role');
const permissions = jwtService.getClaim<string[]>(token, 'permissions');
const userId = jwtService.getClaim<number>(token, 'userId');