Skip to main content
Version: 0.5.0 (Previous)

🏢 Organization Routes

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

🎯 Overview​

Organization routes are designed to:

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

📋 Route Structure​

Each organization route follows a consistent pattern:

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

🔧 Available Organization Routes​

createOrganizationRoute​

Creates a new organization and returns the created resource.

Purpose: Handles organization creation with full resource retrieval

Route Details:

  • Method: POST
  • Path: /organizations
  • Authentication: Required (Bearer token)

Blocks: createOrganization, getOrganizationById, calculateChildAncestors, normalizeLogoOfOwner Terminators: normalizeOrganizationTerminator

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

Usage:

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

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

getOrganizationRoute​

Retrieves a specific organization by ID.

Purpose: Fetches organization data with access control

Route Details:

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

Blocks: getOrganizationById, normalizeLogoOfOwner Terminators: normalizeOrganizationTerminator

Validators: isAuthenticated, some(checkIdentityType(['admin']), hasOrgRole(['owner', 'admin', 'member'], ['params', 'requestParams', 'organizationId']))

Usage:

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

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

findOrganizationsRoute​

Retrieves all organizations with normalized list format.

Purpose: Lists organizations with pagination and access control

Route Details:

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

Blocks: findOrganizations, normalizeLogosOfOwners Terminators: normalizeOrganizationsListTerminator

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

Usage:

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

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

updateOrganizationRoute​

Updates an existing organization and returns the updated resource.

Purpose: Modifies organization data with access control

Route Details:

  • Method: PATCH
  • Path: /organizations/:organizationId
  • Authentication: Required (Bearer token)

Blocks: updateOrganization, getOrganizationById, normalizeLogoOfOwner Terminators: normalizeOrganizationTerminator

Validators: isAuthenticated, some(checkIdentityType(['admin']), hasOrgRole(['owner'], ['params', 'requestParams', 'organizationId']))

Usage:

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

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

deleteOrganizationRoute​

Deletes an organization by ID.

Purpose: Removes organization with access control

Route Details:

  • Method: DELETE
  • Path: /organizations/:organizationId
  • Authentication: Required (Bearer token)

Blocks: getOrganizationById, deleteLogoOfOwner, deleteOrganization Terminators: deleteOrganizationTerminator

Validators: isAuthenticated, some(checkIdentityType(['admin']), hasOrgRole(['owner'], ['params', 'requestParams', 'organizationId']))

Usage:

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

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

getOrganizationMemberRoleRoute​

Retrieves the role of a specific member within an organization.

Purpose: Fetches member role within organization

Route Details:

  • Method: GET
  • Path: /organizations/:organizationId/members/:identityId/role
  • Authentication: Required (Bearer token)

Blocks: getOrganizationById, buildOrganizationsForMemberByIdsQuery, findOrganizations, calculateMemberRole

Validators: isAuthenticated, some(checkIdentityType(['admin']), hasOrgRole(['owner', 'admin'], ['params', 'requestParams', 'organizationId']))

Usage:

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

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

checkOrganizationMemberExistenceRoute​

Checks if a member exists within an organization.

Purpose: Verifies member membership in organization

Route Details:

  • Method: GET
  • Path: /organizations/:organizationId/members/check-existence
  • Authentication: Required (Bearer token)

Blocks: getOrganizationById, checkOrganizationMemberExistence Terminators: normalizeOrganizationMemberExistenceTerminator

Validators: isAuthenticated, some(checkIdentityType(['admin']), hasOrgRole(['owner', 'admin'], ['params', 'requestParams', 'organizationId']))

Usage:

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

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

findOrganizationMembersRoute​

Retrieves all members within an organization.

Purpose: Lists organization members

Route Details:

  • Method: GET
  • Path: /organizations/:organizationId/members
  • Authentication: Required (Bearer token)

Blocks: findOrganizationMembers Terminators: normalizeOrganizationMembersListTerminator

Validators: isAuthenticated, some(checkIdentityType(['admin']), hasOrgRole(['owner', 'admin'], ['params', 'requestParams', 'organizationId']))

Usage:

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

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

upsertOrganizationMembersRoute​

Creates or updates members within an organization.

Purpose: Manages organization member memberships

Route Details:

  • Method: PATCH
  • Path: /organizations/:organizationId/members
  • Authentication: Required (Bearer token)

Blocks: getOrganizationById, upsertOrganizationMembers Terminators: upsertOrganizationMembersTerminator

Validators: isAuthenticated, some(checkIdentityType(['admin']), hasOrgRole(['owner', 'admin'], ['params', 'requestParams', 'organizationId']))

Usage:

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

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

deleteOrganizationMemberRoute​

Removes a member from an organization.

Purpose: Removes member from organization membership

Route Details:

  • Method: DELETE
  • Path: /organizations/:organizationId/members/:identityId
  • Authentication: Required (Bearer token)

Blocks: deleteOrganizationMember Terminators: deleteOrganizationMemberTerminator

Validators: isAuthenticated, some(checkIdentityType(['admin']), hasOrgRole(['owner', 'admin'], ['params', 'requestParams', 'organizationId']))

Usage:

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

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

findOrganizationsForMemberRoute​

Retrieves all organizations for a specific identity (member). Supports optional inclusion of inherited roles from descendant organizations via the includeInherited=true query parameter.

Purpose: Lists organizations where identity is a member, with optional inherited roles

Route Details:

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

Blocks: buildOrganizationsForMemberByRoleQuery, findOrganizations, normalizeLogosOfOwners, buildOrganizationsWithDescendantsQuery, extractAncestors, buildOrganizationsForMemberByIdsQuery, calculateMemberRoleForOrganizations, normalizeOrganizationsForMember

Terminators: Formats organizations list with role information; success/error mapping via orThrow

Validators: isAuthenticated, some(checkIdentityType(['admin']), isSelf(['params', 'requestParams', 'identityId']))

Usage:

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

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

getLogoUploadUrlRoute​

Generates signed upload URL for organization logo via GET /organizations/:organizationId/logo-upload-url.

Purpose: Issues a pre-signed URL to upload an organization logo securely.

Route Details:

  • Method: GET
  • Path: /organizations/:organizationId/logo-upload-url
  • Authentication: Required (Bearer token)

Blocks: generateSignedLogoUploadUrl Terminators: Built-in success/error mapping via orThrow

Validators: isAuthenticated, some(checkIdentityType(['admin']), hasOrgRole(['owner'], ['params', 'requestParams', 'organizationId']))

Usage:

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

// Use in feature composition:
export const logoUploadFeature = compose(logoUploadSchema, getLogoUploadUrlRoute);

findOrganizationDescendantsRoute​

Retrieves all descendant organizations for a given organization.

Purpose: Lists descendants in the organization tree; supports depth via ?depth=<n> query parameter

Route Details:

  • Method: GET
  • Path: /organizations/:organizationId/descendants
  • Authentication: Required (Bearer token)

Blocks: getOrganizationById, buildDescendantsQuery, findOrganizations, normalizeOrganizations

Terminators: Normalizes descendant organizations list with success/error mapping via orThrow

Validators: isAuthenticated, some(checkIdentityType(['admin']), hasOrgRole(['owner', 'admin'], ['params', 'requestParams', 'organizationId']))

Usage:

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

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