@hsuite/api-key NPM

@hsuite/api-key

A comprehensive NestJS module for API key-based authentication, providing a complete solution for protecting routes and validating API keys in your application.

Features

🔐 API key validation and authentication
🛡️ Route protection through guards
🔄 Passport.js integration
🌐 Global or feature-module registration
📦 Built-in user integration
🔑 Bearer token support in Authorization header

Installation

npm install @hsuite/api-key

Peer Dependencies

This module requires the following peer dependencies:

{
  "@nestjs/common": "^10.4.2",
  "@nestjs/core": "^10.4.2"
}

Quick Start

Import the module in your app.module.ts:

import { ApiKeyModule } from '@hsuite/api-key';

@Module({
  imports: [
    ApiKeyModule.forRoot() // Register globally
  ]
})
export class AppModule {}

Protect your routes using the guard:

import { ApiKeyAuthGuard } from '@hsuite/api-key';

@UseGuards(ApiKeyAuthGuard)
@Controller('api')
export class ApiController {
  @Get('protected')
  getProtectedResource() {
    return 'This route is protected by API key authentication';
  }
}

API Reference

ApiKeyModule

The main module that provides API key authentication functionality.

Methods

forRoot(): Registers the module globally in your application.

ApiKeyService

Service responsible for API key operations and validation.

Methods

validateApiKey(apiKey: string, user: UserDocument): Promise<User>
- Validates an API key against a user's stored credentials
- Returns the user object if valid, null otherwise

ApiKeyAuthGuard

Guard that protects routes requiring API key authentication.

ApiKeyStrategy

Passport strategy implementation for API key authentication.

Usage Examples

Protecting Routes

// Protect a single route
@UseGuards(ApiKeyAuthGuard)
@Get('resource')
getResource() {
  return 'Protected resource';
}

// Protect an entire controller
@UseGuards(ApiKeyAuthGuard)
@Controller('api')
export class ApiController {
  // All routes require API key authentication
}

Making Authenticated Requests

Clients should include the API key in the Authorization header using the Bearer scheme:

Authorization: Bearer your-api-key-here

Validating API Keys

@Injectable()
export class YourService {
  constructor(private apiKeyService: ApiKeyService) {}

  async validateKey(apiKey: string, user: UserDocument) {
    const validUser = await this.apiKeyService.validateApiKey(apiKey, user);
    if (validUser) {
      // API key is valid
    }
  }
}