HbarSuite Docs
  • Welcome to HbarSuite
  • HbarSuite Developer Documentation
    • HbarSuite Smart Engine Applications
      • @hsuite/cross-chain-exchange
      • @hsuite/dao
      • @hsuite/exchange
      • @hsuite/launchpad
      • @hsuite/multisig
      • @hsuite/nft-exchange
    • HSuite Libraries
      • @hsuite/api-key
      • @hsuite/auth-types
      • @hsuite/auth
      • @hsuite/client-types
      • @hsuite/client
      • @hsuite/dkg-types
      • @hsuite/hashgraph-types
      • @hsuite/health
      • @hsuite/helpers
      • @hsuite/ipfs
      • @hsuite/smart-config
      • @hsuite/smart-network-types
      • @hsuite/smart-transaction-types
      • @hsuite/smartnode-sdk
      • @hsuite/snapshots
      • @hsuite/subscriptions-types
      • @hsuite/subscriptions
      • @hsuite/throttler-types
      • @hsuite/throttler
      • @hsuite/users-types
      • @hsuite/users
      • @hsuite/validators-types
  • General Documentation
    • Tokenomics
      • Tokenomics v1
      • Tokenomics V2
    • Smart Apps and Interaction
      • Subscription-Based Model
      • Token-Gate Model
    • The Smart Node Network
      • security-layer
        • Security Layer Integration
        • Setting Up Secure Clusters
        • Generating and Sharing Keys Collaboratively
        • Protecting Secrets with Shamir's Method
        • Managing Cluster Membership
        • Handling Node Expulsion and Replacement
        • Automating Responses to Network Changes & Key Rotation
        • Ensuring Continuous Operation and Recovery
      • Understanding Validators in Our System
        • Type of Validators Explained
    • What is a Smart Node?
  • Restful APIs Documentation
Powered by GitBook
On this page
  • Features
  • Installation
  • Peer Dependencies
  • Quick Start
  • API Reference
  • ApiKeyModule
  • ApiKeyService
  • ApiKeyAuthGuard
  • ApiKeyStrategy
  • Usage Examples
  • Protecting Routes
  • Making Authenticated Requests
  • Validating API Keys
  • Architecture
  • Documentation
  • Version
  • License
  1. HbarSuite Developer Documentation
  2. HSuite Libraries

@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

  1. Import the module in your app.module.ts:

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

@Module({
  imports: [
    ApiKeyModule.forRoot() // Register globally
  ]
})
export class AppModule {}
  1. 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
    }
  }
}

Architecture

The module consists of several key components:

  1. ApiKeyModule: The main module that ties everything together

  2. ApiKeyService: Handles API key validation and management

  3. ApiKeyAuthGuard: Protects routes requiring authentication

  4. ApiKeyStrategy: Implements the Passport.js authentication strategy

Documentation

Detailed documentation can be generated using Compodoc:

npm run compodoc

To check documentation coverage:

npm run compodoc:coverage

Version

Current version: 2.0.0

License

This package is part of the HSuite Enterprise solution.

Built with ❤️ by the HbarSuite Team Copyright © 2024 HbarSuite. All rights reserved.

PreviousHSuite LibrariesNext@hsuite/auth-types

Last updated 3 months ago