Skip to main content
Version: 🚧 Canary

🛣️ Identity Routes

Identity routes provide pre-configured HTTP endpoints for identity management operations in NodeBlocks applications. These routes combine blocks, validators, and middleware to create complete API endpoints with proper authentication, authorization, and error handling.

🎯 Overview​

Identity routes are designed to:

  • Provide complete API endpoints for identity management operations
  • Combine blocks with validators for secure operations
  • Include authentication and authorization checks
  • Support functional composition patterns
  • Handle logging and error management automatically

📋 Route Structure​

Each identity route follows a consistent pattern:

  • HTTP Method: Defines the operation type (GET, PATCH, DELETE)
  • Path: Specifies the endpoint URL with parameters
  • Handler: Composed function chain for business logic
  • Validators: Authentication and authorization checks

🔧 Available Identity Routes​

getIdentityRoute​

Retrieves a specific identity by ID.

Purpose: Fetches identity data with access control

Route Details:

  • Method: GET
  • Path: /identities/:identityId
  • Authentication: Required (Bearer token)

Blocks: getIdentityById, normalizeIdentity (from authentication)

Validators: isAuthenticated, checkIdentityType(['admin'])

Usage:

import { routes } from '@nodeblocks/backend-sdk';

// Register route with Express app
app.use('/api', routes.getIdentityRoute);

findIdentitiesRoute​

Retrieves all identities with normalized list format.

Purpose: Lists identities with pagination and admin-only access

Route Details:

  • Method: GET
  • Path: /identities
  • Authentication: Required (Bearer token)

Blocks: findIdentities, normalizeIdentitiesWithoutPassword (from authentication)

Validators: isAuthenticated, checkIdentityType(['admin'])

Usage:

import { routes } from '@nodeblocks/backend-sdk';

// Register route with Express app
app.use('/api', routes.findIdentitiesRoute);

updateIdentityRoute​

Updates an existing identity and returns the updated resource.

Purpose: Modifies identity data with access control

Route Details:

  • Method: PATCH
  • Path: /identities/:identityId
  • Authentication: Required (Bearer token)

Blocks: updateIdentity, getIdentityById, normalizeIdentity (from authentication)

Validators: isAuthenticated, checkIdentityType(['admin'])

Usage:

import { routes } from '@nodeblocks/backend-sdk';

// Register route with Express app
app.use('/api', routes.updateIdentityRoute);

deleteIdentityRoute​

Deletes an identity by ID.

Purpose: Removes identity with access control

Route Details:

  • Method: DELETE
  • Path: /identities/:identityId
  • Authentication: Required (Bearer token)

Blocks: deleteIdentity, deleteIdentityTerminator

Validators: isAuthenticated, checkIdentityType(['admin'])

Usage:

import { routes } from '@nodeblocks/backend-sdk';

// Register route with Express app
app.use('/api', routes.deleteIdentityRoute);

lockIdentityRoute​

Locks an identity via POST /identities/:identityId/lock.

Purpose: Locks an identity for security purposes with admin access control.

Route Details:

  • Method: POST
  • Path: /identities/:identityId/lock
  • Authentication: Required (Bearer token)

Blocks: buildLockIdentityPayload, updateIdentity, orThrow

Validators: isAuthenticated, checkIdentityType(['admin'])

Usage:

import { routes } from '@nodeblocks/backend-sdk';

// Register route with Express app
app.use('/api', routes.lockIdentityRoute);

Response (204 No Content):

{}

Error Responses:

  • 401: Unauthorized - Invalid or missing authentication token
  • 403: Forbidden - User lacks admin privileges
  • 404: Not Found - Identity does not exist
  • 500: Internal Server Error - Database operation failed

Key Features:

  • Authorization Control: Restricts access to admin users
  • Atomic Operations: Uses MongoDB atomic update operations
  • Comprehensive Error Handling: Specific error responses for different failure scenarios

unlockIdentityRoute​

Unlocks a locked identity via POST /identities/:identityId/unlock.

Purpose: Unlocks a previously locked identity with admin access control.

Route Details:

  • Method: POST
  • Path: /identities/:identityId/unlock
  • Authentication: Required (Bearer token)

Blocks: buildUnlockIdentityPayload, updateIdentity, orThrow

Validators: isAuthenticated, checkIdentityType(['admin'])

Usage:

import { routes } from '@nodeblocks/backend-sdk';

// Register route with Express app
app.use('/api', routes.unlockIdentityRoute);

Response (204 No Content):

{}

Error Responses:

  • 401: Unauthorized - Invalid or missing authentication token
  • 403: Forbidden - User lacks admin privileges
  • 404: Not Found - Identity does not exist
  • 500: Internal Server Error - Database operation failed

Key Features:

  • Authorization Control: Restricts access to admin users
  • Atomic Operations: Uses MongoDB atomic update operations
  • Comprehensive Error Handling: Specific error responses for different failure scenarios

🔗 Related Documentation​