npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@wisemen/nestjs-zitadel

v0.3.0

Published

A NestJS client for the Zitadel v2 API, the v2beta Project, Application, Internal Permission, Authorization, Instance and Action APIs, and the v1 Management and Admin APIs. The package provides a `ZitadelClient` that exposes the Zitadel gRPC service clien

Readme

@wisemen/nestjs-zitadel

A NestJS client for the Zitadel v2 API, the v2beta Project, Application, Internal Permission, Authorization, Instance and Action APIs, and the v1 Management and Admin APIs. The package provides a ZitadelClient that exposes the Zitadel gRPC service clients, plus a ZitadelModule that registers it in Nest DI with configuration resolved at the application boundary.

Register The Module

Use ZitadelModule.forRootAsync(...) when the connection settings come from ConfigService or another application-specific source.

import { Module } from '@nestjs/common'
import { ConfigModule, ConfigService } from '@nestjs/config'
import {
  ZitadelModule,
  type ZitadelModuleAsyncOptions,
  type ZitadelOptions
} from '@wisemen/nestjs-zitadel'

@Module({
  imports: [
    ZitadelModule.forRootAsync({
      imports: [ConfigModule],
      inject: [ConfigService],
      useFactory: (configService: ConfigService): ZitadelOptions => ({
        baseUrl: configService.getOrThrow('ZITADEL_BASE_URL'),
        apiToken: configService.getOrThrow('ZITADEL_API_TOKEN'),
        organisationId: configService.get('ZITADEL_ORGANISATION_ID')
      })
    } satisfies ZitadelModuleAsyncOptions)
  ]
})
export class IdentityModule {}

Use forRoot(...) when the values are already available statically.

Inject The Client

import { Injectable } from '@nestjs/common'
import { ZitadelClient } from '@wisemen/nestjs-zitadel'

@Injectable()
export class SyncUserFromZitadelUseCase {
  constructor (
    private readonly zitadelClient: ZitadelClient
  ) {}

  async execute (userId: string): Promise<void> {
    await this.zitadelClient.userClient.getUserByID({ userId })
  }
}

v2beta Clients

ZitadelClient exposes v2beta clients for resources that have no stable v2 API yet:

  • projectClient (ProjectService): projects, roles and project grants
  • applicationClient (AppService): applications and application keys
  • permissionClient (InternalPermissionService): administrators (instance, organization and project members)
  • authorizationClient (AuthorizationService): authorizations (user grants of project roles)
  • instanceClient (InstanceService): the instance and its custom and trusted domains
  • actionClient (ActionService): Actions v2 targets and executions
const { id: projectId } = await zitadelClient.projectClient.createProject({
  organizationId: zitadelClient.defaultOrganizationId,
  name: 'my-project',
  projectRoleAssertion: false,
  authorizationRequired: false,
  projectAccessRequired: false
})

These APIs are in beta: request and response shapes can still change between ZITADEL releases. Prefer them over the v1 clients for new code.

v1 Management And Admin Clients

ZitadelClient also exposes the v1 managementClient and adminClient, created on the same authenticated transport as the v2 clients:

const { project } = await zitadelClient.managementClient.addProject({ name: 'my-project' })
await zitadelClient.adminClient.listIAMMembers({})

ZITADEL has deprecated the v1 Management and Admin APIs. Use these clients only as a fallback for operations that neither the v2 nor the v2beta clients cover. Personal access tokens, for example, are available on the stable v2 userClient (addPersonalAccessToken).

Standalone Usage (Scripts)

The client does not need Nest DI. In a plain Node script (for example a local setup script), construct it directly from resolved options:

import { ZitadelClient, resolveZitadelOptions } from '@wisemen/nestjs-zitadel'

const zitadelClient = new ZitadelClient(resolveZitadelOptions({
  baseUrl: process.env.ZITADEL_BASE_URL!,
  apiToken: process.env.ZITADEL_API_TOKEN!
}))

const { org } = await zitadelClient.managementClient.getMyOrg({})

v1 Management calls act on the organization of the token's user. To target another organization, pass the x-zitadel-orgid header per call:

await zitadelClient.managementClient.addProject(
  { name: 'my-project' },
  { headers: { 'x-zitadel-orgid': zitadelClient.defaultOrganizationId } }
)

The token and error interceptors are applied the same way as inside Nest. The package's peer dependencies (@nestjs/common, reflect-metadata, ...) still need to be installed.

Service User Access Tokens

ZitadelTokenStore gets an access token for a Zitadel service user with the JWT bearer grant. It caches the token until a minute before it expires. createAccessTokenGetter takes either a service user or your own getAccessToken callback. Generated SDKs use it to authenticate.

import { createAccessTokenGetter } from '@wisemen/nestjs-zitadel'

const getAccessToken = createAccessTokenGetter({
  serviceUser: { issuer, serviceUserKey, projectId } // serviceUserKey is the base64-encoded key JSON
})

const token = await getAccessToken()

Errors

Zitadel gRPC errors are mapped to @wisemen/api-error subclasses of ZitadelError (ZitadelBadRequestError, ZitadelConflictError, ZitadelNotFoundError, ZitadelUnauthorizedApiError, ZitadelForbiddenError, ZitadelNotImplementedError, ZitadelInternalError, ZitadelGatewayTimeoutError). Unrecognized errors are wrapped in a ZitadelUnknownError. Reading defaultOrganizationId without an organisationId configured throws ZitadelUnavailableError.