🛣️ Identity routes

Identity routes are SDK composers, not Express middleware. Every endpoint runs isAuthenticated() first, then checkIdentityType(['admin']).

Inventory

Route	Method / protocol	Path	Schema	Validators	Success status
findIdentitiesRoute	GET / HTTP	/identities	findIdentitySchema	isAuthenticated(), checkIdentityType(['admin'])	200
getIdentityRoute	GET / HTTP	/identities/:identityId	getIdentitySchema	isAuthenticated(), checkIdentityType(['admin'])	200
updateIdentityRoute	PATCH / HTTP	/identities/:identityId	updateIdentitySchema	isAuthenticated(), checkIdentityType(['admin'])	200
deleteIdentityRoute	DELETE / HTTP	/identities/:identityId	deleteIdentitySchema	isAuthenticated(), checkIdentityType(['admin'])	204
lockIdentityRoute	POST / HTTP	/identities/:identityId/lock	lockIdentitySchema	isAuthenticated(), checkIdentityType(['admin'])	204
unlockIdentityRoute	POST / HTTP	/identities/:identityId/unlock	unlockIdentitySchema	isAuthenticated(), checkIdentityType(['admin'])	204

Details

findIdentitiesRoute

Implementation

Endpoint: GET /identities

Lists administrator-visible identities. Validators execute in this exact order: isAuthenticated(), then checkIdentityType(['admin']).

Access: Authenticated administrator; use the default Bearer header or the accessToken cookie in cookie mode.

Request: findIdentitySchema accepts optional query fields name (string), page (integer 1–1000), and limit (integer 1–50). The route passes the complete validated request query to findIdentities.

Pipeline: findIdentities → normalizeIdentitiesWithoutPassword → orThrow.

Success: Default 200 JSON array. Each identity is normalized to remove password and MongoDB _id.

Failure: Authentication and administrator validation use the linked shared-validator behavior. findIdentities can produce 500 Failed to find identities.

View complete source

export const findIdentitiesRoute = withRoute({
  handler: compose(
    applyPayloadArgs(
      findIdentities,
      [
        ['context', 'db', 'identities'],
        ['params', 'requestQuery'],
      ],
      'rawIdentities',
    ),
    flatMapAsync(
      applyPayloadArgs(normalizeIdentitiesWithoutPassword, [['context', 'data', 'rawIdentities']], 'identity'),
    ),
    lift(orThrow([], [['context', 'data', 'identity']])),
  ),
  method: 'GET',
  path: '/identities',
  validators: [isAuthenticated(), checkIdentityType(['admin'])],
});

getIdentityRoute

Implementation

Endpoint: GET /identities/:identityId

Retrieves one administrator-visible identity. Validators execute in this exact order: isAuthenticated(), then checkIdentityType(['admin']).

Access: Authenticated administrator; use the default Bearer header or the accessToken cookie in cookie mode.

Request: getIdentitySchema requires the string path parameter identityId.

Pipeline: getIdentityById → normalizeIdentity → orThrow.

Success: Default 200 JSON identity with password and MongoDB _id removed.

Failure: Authentication and administrator validation use the linked shared-validator behavior. getIdentityById can produce 404 Identity not found or 500 Failed to get identity.

View complete source

export const getIdentityRoute = withRoute({
  handler: compose(
    applyPayloadArgs(
      getIdentityById,
      [
        ['context', 'db', 'identities'],
        ['params', 'requestParams', 'identityId'],
      ],
      'rawIdentity',
    ),
    flatMapAsync(applyPayloadArgs(normalizeIdentity, [['context', 'data', 'rawIdentity']], 'identity')),
    lift(orThrow([], [['context', 'data', 'identity']])),
  ),
  method: 'GET',
  path: '/identities/:identityId',
  validators: [isAuthenticated(), checkIdentityType(['admin'])],
});

updateIdentityRoute

Implementation

Endpoint: PATCH /identities/:identityId

Updates and then re-reads an administrator-visible identity. Validators execute in this exact order: isAuthenticated(), then checkIdentityType(['admin']).

Access: Authenticated administrator; use the default Bearer header or the accessToken cookie in cookie mode.

Request: updateIdentitySchema requires string path identityId and a required application/json body. The body is a strict object: optional email (string), emailVerified (boolean), and typeId (string) are the only permitted fields.

Pipeline: updateIdentity → getIdentityById → normalizeIdentity → orThrow.

Success: Default 200 JSON of the re-read identity with password and MongoDB _id removed.

Failure: Authentication and administrator validation use the linked shared-validator behavior. updateIdentity can produce 400, 404 Identity not found, or 500 Failed to update identity; the re-read can additionally produce the linked getIdentityById failures.

View complete source

export const updateIdentityRoute = withRoute({
  handler: compose(
    applyPayloadArgs(
      updateIdentity,
      [
        ['context', 'db', 'identities'],
        ['params', 'requestParams', 'identityId'],
        ['params', 'requestBody'],
      ],
      'identityId',
    ),
    flatMapAsync(
      applyPayloadArgs(
        getIdentityById,
        [
          ['context', 'db', 'identities'],
          ['context', 'data', 'identityId'],
        ],
        'rawIdentity',
      ),
    ),
    flatMapAsync(applyPayloadArgs(normalizeIdentity, [['context', 'data', 'rawIdentity']], 'identity')),
    lift(orThrow([], [['context', 'data', 'identity']])),
  ),
  method: 'PATCH',
  path: '/identities/:identityId',
  validators: [isAuthenticated(), checkIdentityType(['admin'])],
});

deleteIdentityRoute

Implementation

Endpoint: DELETE /identities/:identityId

Deletes an identity. Validators execute in this exact order: isAuthenticated(), then checkIdentityType(['admin']).

Access: Authenticated administrator; use the default Bearer header or the accessToken cookie in cookie mode.

Request: deleteIdentitySchema requires the string path parameter identityId.

Pipeline: deleteIdentity → deleteIdentityTerminator.

Success: 204 with no response body.

Failure: Authentication and administrator validation use the linked shared-validator behavior. deleteIdentity can produce 404 Identity not found or 500 Failed to delete identity; the terminator can produce 500 Unknown error deleting identity.

View complete source

export const deleteIdentityRoute = withRoute({
  handler: compose(
    applyPayloadArgs(
      deleteIdentity,
      [
        ['context', 'db', 'identities'],
        ['params', 'requestParams', 'identityId'],
      ],
      'deleteIdentity',
    ),
    lift(deleteIdentityTerminator),
  ),
  method: 'DELETE',
  path: '/identities/:identityId',
  validators: [isAuthenticated(), checkIdentityType(['admin'])],
});

lockIdentityRoute

Implementation

Endpoint: POST /identities/:identityId/lock

Locks an identity. Validators execute in this exact order: isAuthenticated(), then checkIdentityType(['admin']).

Access: Authenticated administrator; use the default Bearer header or the accessToken cookie in cookie mode.

Request: lockIdentitySchema requires the string path parameter identityId; the schema defines no request body and the route does not read one.

Pipeline: buildLockIdentityPayload → updateIdentity → orThrow. The payload builder and update block are each wrapped in withLogging.

Success: 204 with no response body.

Failure: Authentication and administrator validation use the linked shared-validator behavior. updateIdentity can produce 400, 404 Identity not found, or 500 Failed to update identity.

View complete source

export const lockIdentityRoute = withRoute({
  handler: compose(
    withLogging(applyPayloadArgs(buildLockIdentityPayload, [], 'identityFieldsToUpdate')),
    flatMapAsync(
      withLogging(
        applyPayloadArgs(
          updateIdentity,
          [
            ['context', 'db', 'identities'],
            ['params', 'requestParams', 'identityId'],
            ['context', 'data', 'identityFieldsToUpdate'],
          ],
          'hasUpdatedIdentity',
        ),
      ),
    ),
    // TODO: Go back and refactor errors in identity blocks, then add them here
    lift(orThrow([], [[''], 204])),
  ),
  method: 'POST',
  path: '/identities/:identityId/lock',
  validators: [isAuthenticated(), checkIdentityType(['admin'])],
});

unlockIdentityRoute

Implementation

Endpoint: POST /identities/:identityId/unlock

Unlocks an identity. Validators execute in this exact order: isAuthenticated(), then checkIdentityType(['admin']).

Access: Authenticated administrator; use the default Bearer header or the accessToken cookie in cookie mode.

Request: unlockIdentitySchema requires the string path parameter identityId; the schema defines no request body and the route does not read one.

Pipeline: buildUnlockIdentityPayload → updateIdentity → orThrow. The payload builder and update block are each wrapped in withLogging.

Success: 204 with no response body.

Failure: Authentication and administrator validation use the linked shared-validator behavior. updateIdentity can produce 400, 404 Identity not found, or 500 Failed to update identity.

View complete source

export const unlockIdentityRoute = withRoute({
  handler: compose(
    withLogging(applyPayloadArgs(buildUnlockIdentityPayload, [], 'identityFieldsToUpdate')),
    flatMapAsync(
      withLogging(
        applyPayloadArgs(
          updateIdentity,
          [
            ['context', 'db', 'identities'],
            ['params', 'requestParams', 'identityId'],
            ['context', 'data', 'identityFieldsToUpdate'],
          ],
          'hasUpdatedIdentity',
        ),
      ),
    ),
    // TODO: Go back and refactor errors in identity blocks, then add them here
    lift(orThrow([], [[''], 204])),
  ),
  method: 'POST',
  path: '/identities/:identityId/unlock',
  validators: [isAuthenticated(), checkIdentityType(['admin'])],
});