feat(API): Add user management endpoints to the Projects Public API

packages/@n8n/api-types/src/dto/index.ts

@@ -24,6 +24,8 @@ export { ChangePasswordRequestDto } from './password-reset/change-password-reque
 export { CreateProjectDto } from './project/create-project.dto';
 export { UpdateProjectDto } from './project/update-project.dto';
 export { DeleteProjectDto } from './project/delete-project.dto';
+export { AddUsersToProjectDto } from './project/add-users-to-project.dto';
+export { ChangeUserRoleInProject } from './project/change-user-role-in-project.dto';
 
 export { SamlAcsDto } from './saml/saml-acs.dto';
 export { SamlPreferences } from './saml/saml-preferences.dto';

packages/@n8n/api-types/src/dto/project/__tests__/add-users-to-project.dto.test.ts

@@ -0,0 +1,138 @@
+import { AddUsersToProjectDto } from '../add-users-to-project.dto';
+
+describe('AddUsersToProjectDto', () => {
+	describe('Valid requests', () => {
+		test.each([
+			{
+				name: 'with single user',
+				request: {
+					relations: [
+						{
+							userId: 'user-123',
+							role: 'project:admin',
+						},
+					],
+				},
+			},
+			{
+				name: 'with multiple relations',
+				request: {
+					relations: [
+						{
+							userId: 'user-123',
+							role: 'project:admin',
+						},
+						{
+							userId: 'user-456',
+							role: 'project:editor',
+						},
+						{
+							userId: 'user-789',
+							role: 'project:viewer',
+						},
+					],
+				},
+			},
+			{
+				name: 'with all possible roles',
+				request: {
+					relations: [
+						{ userId: 'user-1', role: 'project:personalOwner' },
+						{ userId: 'user-2', role: 'project:admin' },
+						{ userId: 'user-3', role: 'project:editor' },
+						{ userId: 'user-4', role: 'project:viewer' },
+					],
+				},
+			},
+		])('should validate $name', ({ request }) => {
+			const result = AddUsersToProjectDto.safeParse(request);
+			expect(result.success).toBe(true);
+		});
+	});
+
+	describe('Invalid requests', () => {
+		test.each([
+			{
+				name: 'missing relations array',
+				request: {},
+				expectedErrorPath: ['relations'],
+			},
+			{
+				name: 'empty relations array',
+				request: {
+					relations: [],
+				},
+				expectedErrorPath: ['relations'],
+			},
+			{
+				name: 'invalid userId type',
+				request: {
+					relations: [
+						{
+							userId: 123,
+							role: 'project:admin',
+						},
+					],
+				},
+				expectedErrorPath: ['relations', 0, 'userId'],
+			},
+			{
+				name: 'empty userId',
+				request: {
+					relations: [
+						{
+							userId: '',
+							role: 'project:admin',
+						},
+					],
+				},
+				expectedErrorPath: ['relations', 0, 'userId'],
+			},
+			{
+				name: 'invalid role',
+				request: {
+					relations: [
+						{
+							userId: 'user-123',
+							role: 'invalid-role',
+						},
+					],
+				},
+				expectedErrorPath: ['relations', 0, 'role'],
+			},
+			{
+				name: 'missing role',
+				request: {
+					relations: [
+						{
+							userId: 'user-123',
+						},
+					],
+				},
+				expectedErrorPath: ['relations', 0, 'role'],
+			},
+			{
+				name: 'invalid relations array type',
+				request: {
+					relations: 'not-an-array',
+				},
+				expectedErrorPath: ['relations'],
+			},
+			{
+				name: 'invalid user object in array',
+				request: {
+					relations: ['not-an-object'],
+				},
+				expectedErrorPath: ['relations', 0],
+			},
+		])('should fail validation for $name', ({ request, expectedErrorPath }) => {
+			const result = AddUsersToProjectDto.safeParse(request);
+
+			expect(result.success).toBe(false);
+
+			if (expectedErrorPath) {
+				expect(result.error?.issues[0].path).toEqual(expectedErrorPath);
+			}
+		});
+	});
+});

packages/@n8n/api-types/src/dto/project/__tests__/change-user-role-in-project.dto.test.ts

@@ -0,0 +1,54 @@
+import { ChangeUserRoleInProject } from '../change-user-role-in-project.dto';
+
+describe('ChangeUserRoleInProject', () => {
+	describe('Allow valid roles', () => {
+		test.each(['project:admin', 'project:editor', 'project:viewer'])('should allow %s', (role) => {
+			const result = ChangeUserRoleInProject.safeParse({ role });
+			expect(result.success).toBe(true);
+		});
+	});
+
+	describe('Reject invalid roles', () => {
+		test.each([
+			{
+				name: 'missing role',
+				request: {},
+				expectedErrorPath: ['role'],
+			},
+			{
+				name: 'empty role',
+				request: {
+					role: '',
+				},
+				expectedErrorPath: ['role'],
+			},
+			{
+				name: 'invalid role type',
+				request: {
+					role: 123,
+				},
+				expectedErrorPath: ['role'],
+			},
+			{
+				name: 'invalid role value',
+				request: {
+					role: 'invalid-role',
+				},
+				expectedErrorPath: ['role'],
+			},
+			{
+				name: 'personal owner role',
+				request: { role: 'project:personalOwner' },
+				expectedErrorPath: ['role'],
+			},
+		])('should reject $name', ({ request, expectedErrorPath }) => {
+			const result = ChangeUserRoleInProject.safeParse(request);
+
+			expect(result.success).toBe(false);
+
+			if (expectedErrorPath) {
+				expect(result.error?.issues[0].path).toEqual(expectedErrorPath);
+			}
+		});
+	});
+});

packages/@n8n/api-types/src/dto/project/add-users-to-project.dto.ts

@@ -0,0 +1,8 @@
+import { z } from 'zod';
+import { Z } from 'zod-class';
+
+import { projectRelationSchema } from '../../schemas/project.schema';
+
+export class AddUsersToProjectDto extends Z.class({
+	relations: z.array(projectRelationSchema).min(1),
+}) {}

packages/@n8n/api-types/src/dto/project/change-user-role-in-project.dto.ts

@@ -0,0 +1,7 @@
+import { Z } from 'zod-class';
+
+import { projectRoleSchema } from '../../schemas/project.schema';
+
+export class ChangeUserRoleInProject extends Z.class({
+	role: projectRoleSchema.exclude(['project:personalOwner']),
+}) {}

packages/@n8n/api-types/src/schemas/project.schema.ts

@@ -20,7 +20,7 @@ export const projectRoleSchema = z.enum([
 export type ProjectRole = z.infer<typeof projectRoleSchema>;
 
 export const projectRelationSchema = z.object({
-	userId: z.string(),
-	role: projectRoleSchema,
+	userId: z.string().min(1),
+	role: projectRoleSchema.exclude(['project:personalOwner']),
 });
 export type ProjectRelation = z.infer<typeof projectRelationSchema>;

packages/cli/src/controllers/project.controller.ts

@@ -25,11 +25,7 @@ import { NotFoundError } from '@/errors/response-errors/not-found.error';
 import { EventService } from '@/events/event.service';
 import type { ProjectRequest } from '@/requests';
 import { AuthenticatedRequest } from '@/requests';
-import {
-	ProjectService,
-	TeamProjectOverQuotaError,
-	UnlicensedProjectRoleError,
-} from '@/services/project.service.ee';
+import { ProjectService, TeamProjectOverQuotaError } from '@/services/project.service.ee';
 import { RoleService } from '@/services/role.service';
 
 @RestController('/projects')
@@ -210,16 +206,9 @@ export class ProjectController {
 		if (name || icon) {
 			await this.projectsService.updateProject(projectId, { name, icon });
 		}
-		if (relations) {
-			try {
-				await this.projectsService.syncProjectRelations(projectId, relations);
-			} catch (e) {
-				if (e instanceof UnlicensedProjectRoleError) {
-					throw new BadRequestError(e.message);
-				}
-				throw e;
-			}
 
+		if (relations) {
+			await this.projectsService.syncProjectRelations(projectId, relations);
 			this.eventService.emit('team-project-updated', {
 				userId: req.user.id,
 				role: req.user.role,

packages/cli/src/public-api/v1/handlers/projects/projects.handler.ts

@@ -1,11 +1,19 @@
-import { CreateProjectDto, DeleteProjectDto, UpdateProjectDto } from '@n8n/api-types';
+import {
+	AddUsersToProjectDto,
+	ChangeUserRoleInProject,
+	CreateProjectDto,
+	DeleteProjectDto,
+	UpdateProjectDto,
+} from '@n8n/api-types';
 import { Container } from '@n8n/di';
 import type { Response } from 'express';
 
 import { ProjectController } from '@/controllers/project.controller';
 import { ProjectRepository } from '@/databases/repositories/project.repository';
+import { ResponseError } from '@/errors/response-errors/abstract/response.error';
 import type { PaginatedRequest } from '@/public-api/types';
 import type { AuthenticatedRequest } from '@/requests';
+import { ProjectService } from '@/services/project.service.ee';
 
 import { globalScope, isLicensed, validCursor } from '../../shared/middlewares/global.middleware';
 import { encodeNextCursor } from '../../shared/services/pagination.service';
@@ -87,4 +95,67 @@ export = {
 			});
 		},
 	],
+	addUsersToProject: [
+		isLicensed('feat:projectRole:admin'),
+		globalScope('project:update'),
+		async (req: AuthenticatedRequest<{ projectId: string }>, res: Response) => {
+			const payload = AddUsersToProjectDto.safeParse(req.body);
+			if (payload.error) {
+				return res.status(400).json(payload.error.errors[0]);
+			}
+
+			try {
+				await Container.get(ProjectService).addUsersToProject(
+					req.params.projectId,
+					payload.data.relations,
+				);
+			} catch (error) {
+				if (error instanceof ResponseError) {
+					return res.status(error.httpStatusCode).send({ message: error.message });
+				}
+				throw error;
+			}
+
+			return res.status(201).send();
+		},
+	],
+	changeUserRoleInProject: [
+		isLicensed('feat:projectRole:admin'),
+		globalScope('project:update'),
+		async (req: AuthenticatedRequest<{ projectId: string; userId: string }>, res: Response) => {
+			const payload = ChangeUserRoleInProject.safeParse(req.body);
+			if (payload.error) {
+				return res.status(400).json(payload.error.errors[0]);
+			}
+
+			const { projectId, userId } = req.params;
+			const { role } = payload.data;
+			try {
+				await Container.get(ProjectService).changeUserRoleInProject(projectId, userId, role);
+			} catch (error) {
+				if (error instanceof ResponseError) {
+					return res.status(error.httpStatusCode).send({ message: error.message });
+				}
+				throw error;
+			}
+
+			return res.status(204).send();
+		},
+	],
+	deleteUserFromProject: [
+		isLicensed('feat:projectRole:admin'),
+		globalScope('project:update'),
+		async (req: AuthenticatedRequest<{ projectId: string; userId: string }>, res: Response) => {
+			const { projectId, userId } = req.params;
+			try {
+				await Container.get(ProjectService).deleteUserFromProject(projectId, userId);
+			} catch (error) {
+				if (error instanceof ResponseError) {
+					return res.status(error.httpStatusCode).send({ message: error.message });
+				}
+				throw error;
+			}
+			return res.status(204).send();
+		},
+	],
 };