IAuthorizationProvider

Package: @nauth-toolkit/core Type: Interface

Decides whether a privileged (admin) operation may proceed. Consulted by AdminAuthService, MFAService, ApiKeyService and AuthAuditService before each admin method runs. See Authorization for how to write one.

NestJS

import type { IAuthorizationProvider, AuthorizationContext, AuthorizationDecision, AuthAction } from '@nauth-toolkit/nestjs';

Express

import type { IAuthorizationProvider, AuthorizationContext, AuthorizationDecision, AuthAction } from '@nauth-toolkit/core';

Fastify

import type { IAuthorizationProvider, AuthorizationContext, AuthorizationDecision, AuthAction } from '@nauth-toolkit/core';

Methods

Method	Returns	Description
authorize(context)	Promise<AuthorizationDecision> | AuthorizationDecision	Decide whether context.action may proceed. Throwing is treated as a denial.

AuthorizationContext

Passed to authorize().

Property	Type	Description
action	AuthAction	The operation being attempted
actor	IUser | undefined	The authenticated caller. Undefined outside a request; such calls are denied unless wrapped in runAsSystem()
request	NAuthRequest | undefined	The active request, when one exists
targetSub	string | undefined	sub of the user being acted upon. Absent for non-targeted actions such as admin.user.list
viaApiKey	boolean | undefined	True when the caller authenticated with an API key rather than a session

AuthorizationDecision

Returned from authorize().

Property	Type	Description
allow	boolean	Whether the action may proceed
reason	string | undefined	Surfaced as the FORBIDDEN message and stored on the AUTHORIZATION_DENIED audit record

AuthAction

A closed union of 26 string literals naming each privileged operation independently of any route: admin.user.*, admin.session.*, admin.mfa.*, admin.apiKey.*, admin.audit.*. The full list, with the service method that enforces each one, is in Authorization > Actions.

runAsSystem()

import { runAsSystem } from '@nauth-toolkit/core';

await runAsSystem(async () => {
  // provider is not consulted in here
});

Runs the callback with authorization bypassed. For seeds, migrations, scheduled jobs and tests — code with no authenticated caller. Never call it on a request path.

Configuration

Platform	Where
NestJS	AuthModule.forRoot({ authorization: YourProviderClass }) — a class, registered as a NestJS provider
Express / Fastify	NAuth.create({ authorization: new YourProvider() }) — an instance

See Configuration > Authorization.

Related APIs

• Authorization - Writing and registering a provider
• AdminAuthService - User, password and session admin methods
• MFAService - Admin MFA methods
• Route Groups - The admin group that requires a provider