🆔 Identity

Identity provides administrator-only HTTP endpoints to list, retrieve, update, delete, lock, and unlock identity records through services.identitiesService.

Start here

Mount services.identitiesService below the API prefix. The service's defService router installs express.json() itself; cookie mode additionally requires the host to register cookie-parser before the service router. All six routes require a valid administrator access token, so provide the identities collection, authentication secrets, and configured identity type IDs.

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

const app = express();
app.use(cookieParser()); // Required only when `authMode` is 'cookie'.
app.use(
  '/api',
  services.identitiesService(
    { identities },
    {
      authSecrets: {
        authEncSecret: process.env.AUTH_ENC_SECRET!,
        authSignSecret: process.env.AUTH_SIGN_SECRET!,
      },
      authMode: 'bearer',
      identity: {
        typeIds: {
          admin: 'administrator-type-id',
          guest: 'guest-type-id',
          regular: 'regular-type-id',
        },
      },
    },
  ),
);

Configuration	Default / source behavior	Effect
dataStores.identities	Required	Used by identity blocks and checkIdentityType(['admin']).
authSecrets.authEncSecret, authSecrets.authSignSecret	Required	Used by the selected token-authentication adapter.
authMode	Omitted or 'bearer' uses the Authorization-header adapter; 'cookie' uses request.cookies.accessToken	Selects the protected-route access-token transport.
identity.typeIds.admin	Required at runtime	checkIdentityType(['admin']) compares the caller's loaded typeId with this value.
identity.typeIds.guest, identity.typeIds.regular	Required by the declared typeIds object when it is supplied	Not read by these Identity routes.

Every route runs isAuthenticated() first and checkIdentityType(['admin']) second. The second validator authenticates again while loading and authorizing the caller identity; see Identity validators.

Common tasks

Task	Start with	Contract
List or filter identities	findIdentitiesFeature	findIdentitiesFeature, findIdentitySchema, and findIdentitiesRoute
Retrieve or update one identity	getIdentityRoute	getIdentityRoute, updateIdentitySchema, and updateIdentityRoute
Lock, unlock, or delete an identity	lockIdentityRoute	lockIdentityRoute, unlockIdentityRoute, and deleteIdentityRoute
Reuse identity database helpers	Identity blocks	Identity blocks

Bearer HTTP workflow

With authMode omitted or set to 'bearer', send an administrator access token in the Authorization header.

ACCESS_TOKEN='replace-with-an-administrator-access-token'
curl "https://api.example.test/api/identities?name=Example&page=1&limit=20" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

On success, findIdentitiesRoute returns the default 200 JSON array with password and MongoDB _id removed. A non-administrator caller is rejected with 403; missing token configuration or an invalid token also fails through the shared validator contract.

Cookie HTTP workflow

With authMode: 'cookie', register cookie-parser before the service router and send the accessToken cookie.

IDENTITY_ID='identity-demo-001'
ACCESS_TOKEN='replace-with-an-administrator-access-token'
curl -i -X POST "https://api.example.test/api/identities/$IDENTITY_ID/lock" \
  -H "Cookie: accessToken=$ACCESS_TOKEN"

On success, lockIdentityRoute returns 204 with no body. An absent accessToken cookie produces 401; authorization still requires the configured administrator identity type.

Custom feature composition

This fragment deliberately mounts only identity retrieval and locking. It must provide the same identity datastore, authentication adapter, and configuration context that identitiesService supplies.

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

const identityFeatureComposer = primitives.compose(
  features.getIdentityFeature,
  features.lockIdentityFeature,
);
const identityRouter = primitives.defService(
  partial(identityFeatureComposer, [{
    authenticate: utils.getBearerTokenInfo,
    configuration: {
      authSecrets,
      identity: { typeIds },
    },
    dataStores: { identities },
  }]),
);

app.use('/api', identityRouter);

Reference map

Page	Purpose
Blocks	Identity database operations, state payload builders, and the delete terminator.
Features	Schema-to-route composers mounted by the service.
Routes	Endpoint methods, paths, access rules, statuses, and pipelines.
Schemas	Request contracts and the shared identityId parameter.
Validators	The shared authentication and administrator checks used by every Identity route.

Identity has no handlers.md: the routes compose reusable blocks directly.

Related modules

Authentication supplies the access-token flows and normalizers used by Identity routes. Common validators provides isAuthenticated() and checkIdentityType(['admin']); Common schemas provides shared pagination parameters. Profile consumes findByIdentityIdSchema and buildIdentityIdFilter for its identity-scoped profile lookup.