ZITADEL_DOMAIN=https://example.us1.zitadel.cloud
ZITADEL_CLIENT_ID=your-service-user-client-id
ZITADEL_CLIENT_SECRET=your-service-user-client-secret
ZITADEL_PAT=your-personal-access-token
ZITADEL_KEY_PATH=path/to/jwt-key.json

5. Import the SDK from the copied source:

import Zitadel from './zitadel/index.js';

Public API

Zitadel (default export)

export default class Zitadel {
  public readonly actions: ActionServiceApi;
  public readonly applications: ApplicationServiceApi;
  public readonly authorizations: AuthorizationServiceApi;
  public readonly users: UserServiceApi;
  public readonly sessions: SessionServiceApi;
  public readonly organizations: OrganizationServiceApi;
  public readonly projects: ProjectServiceApi;
  public readonly settings: SettingsServiceApi;
  // ... all other service APIs

  static withPrivateKey(domain: string, keyPath: string): Promise<Zitadel>;
  static withClientCredentials(domain: string, clientId: string, clientSecret: string): Promise<Zitadel>;
  static withPersonalAccessToken(domain: string, token: string): Zitadel;
}

The Zitadel class is the single entry point. Instantiate it with one of the static factory methods corresponding to your auth method, then access API services as properties.

ApiException

export class ApiException extends Error {
  constructor(
    public status: number,
    public headers: { [key: string]: string[] },
    public body: string,
  ) {}
}

Thrown by any service API method when the HTTP response status is outside 200-299. Inspect status and body for error details. Always wrap API calls in a try/catch and check instanceof ApiException.

Configuration

export class Configuration {
  constructor(params?: {
    basePath?: string;
    headers?: HTTPHeaders;
    credentials?: RequestCredentials;
    fetchApi?: FetchAPI;
    middleware?: Middleware[];
  });
}

Controls how all HTTP requests are made. Pass a custom fetchApi to intercept or mock requests in tests, or add middleware for logging and retry logic. Used internally by BaseAPI and all service classes.

Working examples

Scenario - Create a human user with client credentials

Authenticate as a service user via OAuth2 client credentials and create a new human user in Zitadel.

import Zitadel, { ApiException } from './zitadel/index.js';

const zitadel = await Zitadel.withClientCredentials(
  process.env.ZITADEL_DOMAIN!,
  process.env.ZITADEL_CLIENT_ID!,
  process.env.ZITADEL_CLIENT_SECRET!,
);

try {
  const response = await zitadel.users.addHumanUser({
    userServiceAddHumanUserRequest: {
      username: 'jane.doe',
      profile: {
        givenName: 'Jane',
        familyName: 'Doe',
      },
      email: {
        email: 'jane@example.com',
        isVerified: true,
      },
    },
  });
  console.log('Created user:', response.userId);
} catch (e) {
  if (e instanceof ApiException) {
    console.error('API error', e.status, e.body);
  } else {
    throw e;
  }
}

Scenario - List active sessions using a Personal Access Token

Use a PAT (service account token from the Zitadel console) to list all current sessions.

import Zitadel, { ApiException } from './zitadel/index.js';

const zitadel = Zitadel.withPersonalAccessToken(
  process.env.ZITADEL_DOMAIN!,
  process.env.ZITADEL_PAT!,
);

try {
  const response = await zitadel.sessions.listSessions({
    sessionServiceListSessionsRequest: {
      queries: [],
    },
  });
  console.log('Sessions:', JSON.stringify(response.sessions, null, 2));
} catch (e) {
  if (e instanceof ApiException) {
    console.error('Failed to list sessions:', e.status, e.body);
  }
}

Scenario - Create an action target using Private Key JWT

Use a JSON key file (downloaded from the Zitadel console) to authenticate via JWT and register a webhook target for an action.

import Zitadel, { ApiException } from './zitadel/index.js';

const zitadel = await Zitadel.withPrivateKey(
  process.env.ZITADEL_DOMAIN!,
  process.env.ZITADEL_KEY_PATH!,
);

try {
  const response = await zitadel.actions.createTarget({
    actionServiceCreateTargetRequest: {
      name: 'my-webhook',
      restWebhook: {
        url: 'https://my-service.example.com/webhook',
        interruptOnError: true,
      },
      timeout: '10s',
    },
  });
  console.log('Target created:', response.id);
} catch (e) {
  if (e instanceof ApiException) {
    console.error('Error creating target:', e.status, e.body);
  }
}

File walkthrough

• index.ts - Instantiates all service API classes from a shared Configuration and exposes them as typed properties on the Zitadel class; also re-exports everything from models/, auth/, and core files.
• configuration.ts - Holds the Configuration class; controls basePath, request headers, custom fetch, and middleware pipeline.
• runtime.ts - BaseAPI handles actual fetch calls, JSON/MIME detection, and throws ApiException on error responses.
• api-exception.ts - Defines ApiException with HTTP status, headers, and raw body; thrown by BaseAPI.request.
• zitadel-exception.ts - SDK-level ZitadelException for errors not tied to a specific HTTP response.
• transport-options.ts - Exports the TransportOptions type for configuring low-level HTTP transport.
• version.ts - Exports the SDK version string.
• apis/ - Auto-generated API service classes; one per Zitadel service group. Each class extends BaseAPI and exposes methods matching the Zitadel REST API operations.
• auth/ - Authenticator strategy classes and their builders. PersonalAccessAuthenticator, ClientCredentialsAuthenticator, and WebTokenAuthenticator each inject the appropriate Authorization header into Configuration.
• models/ - Auto-generated TypeScript interfaces for all request and response body shapes across every API service.

Common pitfalls and fixes

• ESM import extensions: The source imports with .js extensions. If your bundler or ts-node setup does not support this, use tsx (npx tsx src/index.ts) or configure moduleResolution: "Node16" in tsconfig.json.
• Node.js version below 20: fetch and crypto.subtle are required; upgrade to Node.js 20+ or polyfill with undici explicitly via import { fetch } from 'undici' and pass it as fetchApi to Configuration.
• "type": "module" missing: Without ESM mode in package.json, .js extension imports from the source will fail with ERR_REQUIRE_ESM; add "type": "module" or switch to a bundler.
• Wrong domain format: The domain must include the protocol (https://example.us1.zitadel.cloud), not just the hostname; omitting https:// causes TypeError: Invalid URL.
• PAT scope: A Personal Access Token only has the permissions of the service user it belongs to; if API calls return 403, verify the service user has the required IAM role in the Zitadel console.
• jose / oauth4webapi version mismatch: These packages use ESM-only builds; installing versions older than their ESM-stable releases can break imports. Pin to the versions declared in @zitadel/sdk@4.1.2's lockfile.

Vibe-coding prompt template

I have copied the source of the @zitadel/sdk (version 4.1.2) Node.js SDK into
my project under src/zitadel/. I also have USAGE.md describing the full API.

Please help me integrate this SDK into my existing Express/TypeScript project
step by step:

1. Read USAGE.md and src/zitadel/index.ts to understand available services
   and authentication methods.
2. Add the required runtime dependencies (jose, oauth4webapi, undici) to
   package.json.
3. Create a singleton Zitadel client in src/zitadel-client.ts using the
   correct auth method for my environment (I will tell you which one).
4. Show me how to call the specific Zitadel API I need (I will specify the
   operation), using real method names and model types from src/zitadel/models/.
5. Add proper error handling using ApiException from src/zitadel/api-exception.ts.
6. Ensure all imports use the correct paths relative to src/zitadel/index.ts
   and that ESM module resolution is configured correctly.

My project uses: [describe your stack - Express/Fastify, ts-node/tsx/esbuild, etc.]
My auth method: [withPrivateKey / withClientCredentials / withPersonalAccessToken]
The operation I need: [describe what you want to do with Zitadel]

License and credit

See source/LICENSE if present for the full license text. This block packages the upstream npm package @zitadel/sdk@4.1.2, published by the Zitadel team. Refer to the Zitadel GitHub repository for the original source and contribution guidelines.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.