Backend Accounts Service Guide

Backend Developer Guide — Accounts Service

Overview

The Accounts Service handles user registration, login, and identity. It runs on port 3002 and is accessed by other backend services through the shared Docker backend network.

Direct URL (inside Docker): http://accounts_app:3002
Direct URL (local dev): http://localhost:3002

Other services should NOT call the Accounts Service directly in production — all external traffic goes through the API Gateway. Service-to-service calls within the Docker network are fine.

---

Database — User Entity

The users table is managed by TypeORM and auto-synced in development.

Column	Type	Description
id	UUID	Primary key
auth0Id	string	Auth0's user ID (e.g. `auth0
email	string	Unique email address
name	string	Display name (optional)
role	enum	user, analyst, or admin
createdAt	timestamp	Auto-set on creation
updatedAt	timestamp	Auto-updated

---

UsersService — Available Methods

Import UsersModule in your module to access UsersService.

import { UsersModule } from '../users/users.module';

Find a user by Auth0 ID

Use this when you receive a JWT and need to get the full user record.

const user = await this.usersService.findByAuth0Id('auth0|abc123');

Find a user by email

const user = await this.usersService.findByEmail('user@example.com');

Find all users

const users = await this.usersService.findAll();

Create a user

Normally handled by the registration flow — only use directly if you need to programmatically create users (e.g. seeding).

const user = await this.usersService.create({
  auth0Id: 'auth0|abc123',
  email: 'user@example.com',
  name: 'John Doe',
  role: UserRole.USER,
});

---

Protecting Routes with JWT

Import the guard and strategy into your module:

import { PassportModule } from '@nestjs/passport';
import { JwtStrategy } from './auth/strategies/jwt.strategy';
import { JwtAuthGuard } from './auth/guards/jwt-auth.guard';

Apply the guard to any route that requires authentication:

import { UseGuards, Get, Req } from '@nestjs/common';
import { JwtAuthGuard } from '../auth/guards/jwt-auth.guard';

@Get('protected')
@UseGuards(JwtAuthGuard)
getProtected(@Req() req) {
  // req.user contains { auth0Id, email, role }
  console.log(req.user);
}

---

Roles

The three roles are defined in the User entity:

export enum UserRole {
  ADMIN = 'admin',
  ANALYST = 'analyst',
  USER = 'user',
}

To check a user's role in a route handler:

@Get('admin-only')
@UseGuards(JwtAuthGuard)
adminRoute(@Req() req) {
  if (req.user.role !== 'admin') {
    throw new ForbiddenException('Admins only');
  }
  // ...
}

A proper RolesGuard decorator can be added later as RBAC requirements become clearer.

---

Environment Variables Required

DB_HOST=db
DB_PORT=5432
DB_USERNAME=postgres
DB_PASSWORD=postgres
DB_NAME=phishshield
AUTH0_DOMAIN=your-tenant.us.auth0.com
AUTH0_CLIENT_ID=...
AUTH0_CLIENT_SECRET=...
AUTH0_AUDIENCE=https://phishshield-api
AUTH0_M2M_CLIENT_ID=...
AUTH0_M2M_CLIENT_SECRET=...