Services

The library exposes its core services as injectables. You can use them from anywhere in your app — they're the same services the library's own controllers call.

AuthService

The main facade for auth flows.

Password methods moved. forgotPassword, verifyForgotPasswordOtp, resetPasswordWithToken, and changePassword live on PasswordService, not AuthService.

MfaService

PasswordService

Backs the password endpoints. All four methods take their request DTO and read the current user / tenant from the request context.

Hashing is config-driven. Argon2 hash/verify run on the NestAuthUser entity (setPassword / validatePassword) and honour the password.hash / password.verify hooks — there is no standalone hash() / verify() method on this service.

UserService

ISOLATED mode: getUserByEmail / createUser require a tenantId there (they throw TENANT_ID_REQUIRED without one). Platform super-admins are tenant-less, so provision and look them up with createPlatformUser / getPlatformUserByEmail instead — they never require a tenant and identify the user by the PlatformAccess marker (the same row the login path enforces), so they never return a regular tenant account. Grant roles with user.getPlatformAccess(true) then assignRoles(...). See the platform-admin portal recipe.

For an email/phone-first tenant picker (list which orgs an identity belongs to before login), use getTenantsByEmail / getTenantsByPhone. Those deliberately search across tenants and do not require tenantId. There is no public nest-auth route for them — wire your own endpoint if you need one (rate-limit; return only the fields your UI needs). See Logging in under a tenant (ISOLATED).

RoleService

Manage roles. A "role" is a named bucket — admin, member, owner — scoped to a guard (web, api, mobile, …). It maps many-to-many to permissions.

Permissions are bound to roles by name (scoped to the role's guard), not by ID.

import { Injectable } from '@nestjs/common';
import { RoleService } from '@ackplus/nest-auth';
 
@Injectable()
export class CustomRolesService {
  constructor(private readonly roles: RoleService) {}
 
  async createPortalRole(name: string, permissions: string[]) {
    return this.roles.createRole(
      name,
      'PORTAL',   // guard
      null,       // tenantId
      false,      // isSystem
      permissions,
      true,       // isActive
    );
  }
 
  async findPortalRole(name: string) {
    return this.roles.getRoleByName(name, 'PORTAL');
  }
}

For end-to-end role assignment (creating the role + attaching it to a user × tenant), see the RBAC concept page and the seeding-roles-and-permissions recipe.

PermissionService

The per-action permissions (orders.read, users.delete, …) that roles bundle.

@Injectable()
export class PermissionsBootstrap {
  constructor(private readonly perms: PermissionService) {}
 
  async seedOrders() {
    for (const action of ['read', 'write', 'delete']) {
      await this.perms.createPermission({
        name: `orders.${action}`,
        guard: 'PORTAL',
        category: 'Orders',
        description: `Can ${action} orders`,
      });
    }
  }
}

Permissions are referenced by name in @NestAuthPermissions(...) decorators and in RoleService.createRole(name, guard, …, permissionNames).

User access & platform access

The user × tenant × role[] records are managed through entity methods and UserService — there are no standalone UserAccessService / PlatformAccessService injectables. See User Access & Platform Access for the conceptual split.

Get the membership row off a NestAuthUser (or via UserService), then mutate its roles:

From UserService you can also call setUserAccessRoles(userId, tenantId, roleIds, manager?), ensureUserAccess(userId, tenantId, manager?), and deleteUserAccess(userId, tenantId, manager?).

// Promote a user to a platform (cross-tenant) super-admin role
const user = await this.users.getUserById(userId);
const access = await user.getPlatformAccess(true); // create marker if missing
await access.assignRoles(superAdminRoleIds);

You'll usually call these from your own admin endpoints — there's no public REST surface for them, by design.

TenantService

Tenant lifecycle. Validates slug uniqueness, fires the TenantCreatedEvent / TenantUpdatedEvent / TenantDeletedEvent events.

@Injectable()
export class OnboardingService {
  constructor(
    private readonly tenants: TenantService,
    private readonly users: UserService,
    private readonly roles: RoleService,
  ) {}
 
  async createWorkspace(name: string, ownerId: string) {
    const tenant = await this.tenants.createTenant({
      name,
      slug: slugify(name),
      isActive: true,
      metadata: { plan: 'free' },
    });
 
    // Owner gets the admin role on the new tenant (PORTAL guard)
    const adminRole = await this.roles.getRoleByName('admin', 'PORTAL', tenant.id);
    await this.users.setUserAccessRoles(ownerId, tenant.id, [adminRole.id]);
 
    return tenant;
  }
}

Tenant resolution is driven by tenant.mode: in ISOLATED mode a tenantId is required on signup/login and resolveTenantId throws TENANT_ID_REQUIRED without one; in SHARED mode it can be deferred. See Multi-tenancy.

SessionManagerService

Direct session-store access. Useful for "list this user's active devices" UIs. Public methods include getSession(sessionId), getUserSessions(userId), getActiveSessions(userId), updateSession(sessionId, updates), revokeSession(sessionId, reason?), revokeAllUserSessions(userId), and revokeOtherSessions(userId, currentSessionId).

@Auth()
@Get('me/sessions')
async list(@CurrentUser() user: NestAuthUser) {
  return this.sessions.getActiveSessions(user.id);
}
 
@Auth()
@Delete('me/sessions/:id')
async revoke(@Param('id') id: string) {
  return this.sessions.revokeSession(id, 'logout');
}

JwtService

Token sign/verify primitives. Customize signing via the session.jwt.secret config; you rarely need to call this service directly.

AccessKeyService

API key CRUD — see API Keys.

AuditService

Internal event listener that maps the library's lifecycle events (login, logout, signup, password change, MFA enable/disable, …) onto your audit.onEvent callback. It has no public methods you call directly — wire audit.onEvent in the module config and it forwards IAuthAuditEvent payloads to you.

AuthProviderRegistryService

Read access to the registered auth providers. Use this to render a "sign in with…" button list dynamically:

const providers = registry.getAllProviders();      // BaseAuthProvider[]
const names = providers.map(p => p.providerName);  // ['email', 'google', …]

Also available: getEnabledProviders(), getProvider(name), and hasProvider(name).

AuthConfigService

Frozen snapshot of the resolved module config. Inject this anywhere you need to read the current config:

@Injectable()
class MyService {
  constructor(private readonly auth: AuthConfigService) {}
 
  doStuff() {
    if (this.auth.getOptions().mfa?.required) { … }
  }
}

getConfig() (instance) and the static AuthConfigService.getOptions() both return the resolved IAuthModuleOptions. getRoleGuards() and isRoleGuardAllowed(guard) are convenience accessors for the configured guards.

DebugLoggerService

Conditional logger gated by the debug config. Use it from your own services for log lines you only want when debug is on:

// (message, context?) — also: debug / warn / error / verbose
this.debugLogger.info(`created ${user.id}`, 'UserService');

See Logging & Debugging.

Related

• Decorators.
• Hooks Reference.
• API Reference: Types — full method signatures.