🏢 Organization

Organization provides an SDK service for managing organizations, memberships, hierarchy, change requests, file uploads, and followers through source-composed HTTP features.

Start here

Mount organizationService with the required identities, organizations, and profiles collections. Use express.json() for JSON request bodies; when authMode is 'cookie', register cookie-parser before mounting the service.

import express from 'express';
import cookieParser from 'cookie-parser';
import {services} from '@nodeblocks/backend-sdk';

const app = express();
app.use(express.json());
app.use(cookieParser()); // Required only for authMode: 'cookie'.
app.use('/api', services.organizationService(
  {identities, organizations, profiles},
  {
    authSecrets: {
      authEncSecret: process.env.AUTH_ENC_SECRET!,
      authSignSecret: process.env.AUTH_SIGN_SECRET!,
    },
    authMode: 'bearer',
    identity: {typeIds: {admin: 'identity-type-admin', guest: 'identity-type-guest', regular: 'identity-type-regular'}},
    organization: {roles: {owner: 'owner', admin: 'admin', member: 'member'}},
  },
  {fileStorageDriver},
));

Configuration	Default / source behavior	Effect
authSecrets.authEncSecret / authSecrets.authSignSecret	Required; no runtime default	Service authentication configuration.
authMode	Omitted → 'bearer'	Chooses Bearer-header or cookie authentication.
identity.typeIds	Passed unchanged to validators when supplied	Enables identity-type checks when configured routes invoke them.
organization.roles	Passed unchanged to validators when supplied	Enables role-based Organization checks when configured routes invoke them.

Common tasks

Task	Start with	Contract
Create or retrieve an organization	createOrganizationFeature	createOrganizationFeature and getOrganizationRoute
List organizations or members	findOrganizationsRoute	findOrganizationsRoute and findOrganizationMembersRoute
Maintain members safely	upsertOrganizationMembersRoute	upsertOrganizationMembersRoute and Organization validators
Work with a hierarchy	findOrganizationDescendantsRoute	findOrganizationDescendantsRoute and findOrganizationsForMemberRoute
Submit or review a change request	createChangeRequestRoute	createChangeRequestRoute and findChangeRequestsForOrganizationRoute
Generate an upload URL	getLogoUploadUrlRoute	getLogoUploadUrlRoute and getCertificateUploadUrlRoute

Bearer HTTP workflow

With an authenticated administrator Bearer token, create an organization through createOrganizationRoute. This fragment requires the service mounted above and a valid administrator identity.

export API_BASE_URL='https://api.example.test/api'
export ACCESS_TOKEN='replace-with-a-valid-access-token'
curl --request POST "$API_BASE_URL/organizations" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"ownerId":"identity-owner-001","organization":{"name":"Example organization","description":"Example description","contact_email":"org@example.test"}}'

The route returns the normalized organization on success; authentication or administrator authorization failure is rejected before its pipeline. See the creation schema.

Cookie HTTP workflow

Set authMode: 'cookie' and register cookie-parser; protected routes then read the access token through the configured cookie transport. For example, a member may request an organization using the cookie supplied by the host application:

export API_BASE_URL='https://api.example.test/api'
export ACCESS_COOKIE='accessToken=replace-with-a-valid-access-token'
curl "$API_BASE_URL/organizations/org-001" --header "Cookie: $ACCESS_COOKIE"

The route's access rule is documented with getOrganizationRoute; its path contract is getOrganizationSchema.

Custom feature composition

Features are SDK composers, not Express middleware. A host may compose a single public feature into a service router when it supplies the same runtime context required by the route:

import {partial} from 'ramda';
import {features, primitives, utils} from '@nodeblocks/backend-sdk';

app.use('/api', primitives.defService(partial(features.getOrganizationFeatures, [{
  authenticate: utils.getBearerTokenInfo,
  configuration,
  dataStores: {identities, organizations, profiles},
  fileStorageDriver,
}])));

This fragment requires the host's auth adapter and the collections used by the route. Prefer organizationService when all Organization endpoints are needed.

Reference map

Page	Purpose
Blocks	Reusable organization operations, constants, and errors.
Features	Schema-to-route SDK compositions.
Handlers	Pipeline terminators.
Routes	Endpoint and response contracts.
Schemas	Field-level validation contracts.
Validators	Authentication, role, rank, and ownership guards.

Related modules

Organization service is the service-level reference. Authentication utilities and cookie utilities provide selected token transport. File-storage blocks supply delegated upload/download operations, while Mongo blocks provide paginated database helpers used by Organization routes.