Zitadel Client @bdjawed/zitadel-client

This project provides a client to interact with the Zitadel API. It allows managing users, organizations, projects, and more.

Installation

npm install @bdjawed/zitadel-client

Usage

Client Initialization

import { ZitadelClient } from '@bdjawed/zitadel-client'

const zitadelClient = new ZitadelClient({
  issuerUrl: 'https://your-zitadel-instance.com',
  privateJwtKeyPath: '/path/to/your/private-key.json',
})

await zitadelClient.setup()

Methods

`getUserInfo`

Retrieves the authenticated user's information.

const userInfo = await zitadelClient.auth.getUserInfo()
console.log(userInfo)

`createOrganization`

Creates a new organization.

const organization = await zitadelClient.organization.create({
  name: 'TestOrganization',
})
console.log(organization)

`deleteOrganization`

Deletes an organization.

await zitadelClient.organization.delete('organizationId')
console.log('Organization deleted')

`createHumanUser`

Creates a new human user.

const humanUser = await zitadelClient.userHuman.create({
  username: 'minnie-mouse',
  profile: {
    givenName: 'Minnie',
    familyName: 'Mouse',
    nickName: 'Mini',
    displayName: 'Minnie Mouse',
    preferredLanguage: 'en',
  },
  email: {
    email: 'mini11@mouse.com',
  },
  password: {
    password: 'Secr3tP4ssw0rd!',
    changeRequired: false,
  },
})
console.log(humanUser)

`createMachineUser`

Creates a new machine user.

const machineUser = await zitadelClient.userMachine.create({
  userName: 'TestMachineUser',
  name: 'Test Machine User',
  description: 'Test machine user description',
  accessTokenType: 'JWT',
}, 'organizationId')
console.log(machineUser)

`createMachineUserKey`

Creates a key for a machine user.

const machineUserKey = await zitadelClient.userMachine.key.create('userId', {
  type: 'JSON',
  expirationDate: new Date('2023-12-31'),
}, 'organizationId')
console.log(machineUserKey)

`getMachineUserKeyById`

Retrieves a machine user key by ID.

const machineUserKey = await zitadelClient.userMachine.key.getById({
  userId: 'userId',
  keyId: 'keyId',
}, 'organizationId')
console.log(machineUserKey)

`getMachineUserKeys`

Retrieves the list of keys for a machine user.

const machineUserKeys = await zitadelClient.userMachine.key.list('userId', {
  query: {
    offset: '0',
    limit: 100,
    asc: true,
  },
}, 'organizationId')
console.log(machineUserKeys)

`userDeactivate`

Deactivates a user.

await zitadelClient.user.deactivate('userId')
console.log('User deactivated')

`userReactivate`

Reactivates a user.

await zitadelClient.user.reactivate('userId')
console.log('User reactivated')

`userLock`

Locks a user.

await zitadelClient.user.lock('userId')
console.log('User locked')

`userUnlock`

Unlocks a user.

await zitadelClient.user.unlock('userId')
console.log('User unlocked')

`createMachineUserPAT`

Creates a PAT for a machine user.

const machineUserPat = await zitadelClient.userMachine.pat.create('userId', {
  expirationDate: new Date('2023-12-31'),
}, 'organizationId')
console.log(machineUserPat)

`getMachineUserPAT`

Retrieves a machine user PAT by ID.

const machineUserPat = await zitadelClient.userMachine.pat.getById({
  userId: 'userId',
  tokenId: 'tokenId',
}, 'organizationId')
console.log(machineUserPat)

`getMachineUserPATsList`

Retrieves the list of PATs for a machine user.

const machineUserPats = await zitadelClient.userMachine.pat.list('userId', {
  offset: '0',
  limit: 100,
  asc: true,
}, 'organizationId')
console.log(machineUserPats)

`deleteMachineUserPAT`

Deletes a machine user PAT.

await zitadelClient.userMachine.pat.delete({
  userId: 'userId',
  tokenId: 'tokenId',
}, 'organizationId')
console.log('PAT deleted')

`getUserIDPsList`

Retrieves the list of IDPs for a user.

const userIdps = await zitadelClient.userHuman.idp.list('userId', {
  query: {
    offset: '0',
    limit: 100,
    asc: true,
  },
})
console.log(userIdps)

`deleteMachineUserKey`

Deletes a machine user key by ID.

await zitadelClient.userMachine.key.delete({
  userId: 'userId',
  keyId: 'keyId',
}, 'organizationId')
console.log('Machine user key deleted')

`createProject`

Creates a new project.

const project = await zitadelClient.project.create({
  name: 'TestProject',
  projectRoleAssertion: true,
  projectRoleCheck: true,
  hasProjectCheck: true,
  privateLabelingSetting: 'ENFORCE_PROJECT_RESOURCE_OWNER_POLICY',
}, 'organizationId')
console.log(project)

`createAppApi`

Creates a new API for a project.

const appApi = await zitadelClient.app.create('projectId', {
  name: 'TestAppApi',
  authMethodType: 'BASIC',
}, 'organizationId')
console.log(appApi)

`deleteAppApi`

Deletes an API from a project.

await zitadelClient.app.delete({
  projectId: 'projectId',
  appId: 'appId',
}, 'organizationId')
console.log('App API deleted')

`createAppApiClientSecret`

Creates a client secret for an API.

const appApiClientSecret = await zitadelClient.app.createClientSecret({
  projectId: 'projectId',
  appId: 'appId',
}, 'organizationId')
console.log(appApiClientSecret)

`createAppOidc`

Creates a new OIDC application for a project.

const oidcApp = await zitadelClient.app.createOidc('projectId', {
  name: 'TestOIDCApp',
  redirectUris: ['https://example.com/callback'],
  responseTypes: 'OIDC_RESPONSE_TYPE_CODE',
  grantTypes: 'OIDC_GRANT_TYPE_AUTHORIZATION_CODE',
  appType: 'OIDC_APP_TYPE_WEB',
  authMethodType: 'OIDC_AUTH_METHOD_TYPE_POST',
  postLogoutRedirectUris: [],
  version: 'OIDC_VERSION_1_0',
  devMode: true,
  accessTokenType: 'OIDC_TOKEN_TYPE_JWT',
  accessTokenRoleAssertion: false,
  idTokenRoleAssertion: false,
  idTokenUserinfoAssertion: false,
  clockSkew: '1s',
  additionalOrigins: [],
  skipNativeAppSuccessPage: true,
  backChannelLogoutUri: [],
}, 'organizationId')
console.log(oidcApp)

`updateLoginSettings`

Updates the login settings for the organization.

const loginSettings = await zitadelClient.policies.updateLoginSettings({
  passwordlessType: 'NOT_ALLOWED',
  forceMfa: false,
  allowUsernamePassword: true,
  allowRegister: false,
  allowExternalIdp: true,
  hidePasswordReset: true,
  allowDomainDiscovery: true,
  ignoreUnknownUsernames: true,
  disableLoginWithEmail: true,
  disableLoginWithPhone: true,
})
console.log(loginSettings)

`getLoginSettings`

Retrieves the login settings for the organization.

const loginSettings = await zitadelClient.policies.getLoginSettings('organizationId')
console.log(loginSettings)

`getUserById`

Retrieves a user by ID.

const user = await zitadelClient.user.getById('userId')
console.log(user)

`deleteUserById`

Deletes a user by ID.

await zitadelClient.user.deleteById('userId')
console.log('User deleted')

`getUserByLoginName`

Retrieves a user by login name.

const user = await zitadelClient.user.getByLoginName('loginName')
console.log(user)

`usersSearch`

Searches for users based on the given query.

const users = await zitadelClient.user.search({
  query: {
    offset: '0',
    limit: 100,
    asc: true,
  },
  sortingColumn: 'UNSPECIFIED',
  queries: [
    {
      displayNameQuery: {
        displayName: 't',
        method: 'CONTAINS',
      },
    },
  ],
})
console.log(users)

`getUserHistory`

Retrieves the history of events for a given user.

const userHistory = await zitadelClient.user.getHistory('userId', {
  query: {
    sequence: '0',
    limit: 100,
    asc: true,
  },
}, 'organizationId')
console.log(userHistory)

`isUserUnique`

Checks if a user is unique.

const isUserNameUnique = await zitadelClient.user.isUnique({
  userName: 'minnie-mouse',
}, 'organizationId')
console.log(isUserNameUnique)

`getMetadataByKey`

Retrieves a metadata object from a user by a specific key.

const userMetadata = await zitadelClient.user.metadata.getByKey({
  userId: 'userId',
  key: 'my-key',
}, 'organizationId')
console.log(userMetadata)

`deleteMetadataByKey`

Deletes a metadata object from a user by a specific key.

await zitadelClient.user.metadata.deleteByKey({
  userId: 'userId',
  key: 'my-key',
}, 'organizationId')
console.log('Metadata deleted')

`createMetadataByKey`

Creates metadata for a user with a specific key.

const userMetadata = await zitadelClient.user.metadata.createByKey({
  userId: 'userId',
  key: 'my-key',
}, {
  value: 'VGhpcyBpcyBteSB0ZXN0IHZhbHVl',
}, 'organizationId')
console.log(userMetadata)

`deleteBulkMetadataByKey`

Deletes multiple metadata for a user with the provided keys.

await zitadelClient.user.metadata.bulkDeleteByKey('userId', {
  keys: ['key1', 'key2'],
}, 'organizationId')
console.log('Bulk metadata deleted')

`createBulkMetadataByKey`

Creates multiple metadata objects for a user with the provided keys.

const userMetadataBulk = await zitadelClient.user.metadata.bulkCreateByKey('userId', {
  metadata: [
    { key: 'key1', value: 'value1' },
    { key: 'key2', value: 'value2' },
  ],
}, 'organizationId')
console.log(userMetadataBulk)

`userMetadataSearch`

Searches for user metadata filtered by your query.

const userMetadata = await zitadelClient.user.metadata.search('userId', {
  query: {
    offset: '0',
    limit: 100,
    asc: true,
  },
  queries: [
    {
      keyQuery: {
        key: 'my-key',
        method: 'EQUALS_IGNORE_CASE',
      },
    },
  ],
}, 'organizationId')
console.log(userMetadata)

`deleteUserAvatar`

Deletes a user's avatar.

await zitadelClient.user.deleteAvatar('userId', 'organizationId')
console.log('User avatar deleted')

`updateMachineUser`

Updates a machine user.

const machineUser = await zitadelClient.userMachine.update('userId', {
  name: 'Updated Machine User',
  description: 'Updated machine user description',
  accessTokenType: 'BEARER',
}, 'organizationId')
console.log(machineUser)

`updateHumanUser`

Updates a human user.

const updatedUser = await zitadelClient.userHuman.update('userId', {
  username: 'UpdatedTestHumanUser',
  profile: {
    givenName: 'UpdatedTest',
    familyName: 'User',
    nickName: 'UpdatedTesty',
    displayName: 'UpdatedTesty User',
    preferredLanguage: 'en',
  },
  email: {
    email: 'testy@updated.com',
  },
  password: {
    password: { password: 'Secr3tP4ssw0rd!' },
  },
})
console.log(updatedUser)

`deleteMachineUserSecret`

Deletes a machine user's secret.

await zitadelClient.userMachine.secret.delete('userId', 'organizationId')
console.log('Machine user secret deleted')

`createMachineUserSecret`

Creates a secret for a machine user.

const machineUserSecret = await zitadelClient.userMachine.secret.create('userId', 'organizationId')
console.log(machineUserSecret)

`createUserEmail`

Creates a new email address for a user.

const userEmail = await zitadelClient.user.createEmail('userId', {
  email: 'mini321@mouse.com',
})
console.log(userEmail)

`deleteUserPhone`

Deletes a phone number for a user.

await zitadelClient.user.deletePhone('userId')
console.log('User phone deleted')

`createUserPhone`

Creates a new phone number for a user.

const userPhone = await zitadelClient.user.createPhone('userId', {
  phone: '+1 123 456 7890',
  returnCode: {},
})
console.log(userPhone)

`createUserPassword`

Creates a password for a user.

const userPassword = await zitadelClient.user.createPassword('userId', {
  newPassword: {
    password: 'Secr3tP4ssw0rd!',
    changeRequired: false,
  },
})
console.log(userPassword)

`createUserPasswordResetCode`

Creates a password reset code for a user.

const passwordResetCode = await zitadelClient.user.createPasswordResetCode('userId', {
  returnCode: {},
})
console.log(passwordResetCode)

`resendUserEmailVerificationCode`

Resend the verification code for a user's email address.

const resendVerificationCode = await zitadelClient.user.resendEmailVerificationCode('userId', {
  returnCode: {},
})
console.log(resendVerificationCode)

`resendUserPhoneVerificationCode`

Resend the verification code for a user's phone number.

const resendVerificationCode = await zitadelClient.user.resendPhoneVerificationCode('userId', {
  returnCode: {},
})
console.log(resendVerificationCode)

`getUserAuthMethods`

Retrieves the authentication methods of a user.

const authMethods = await zitadelClient.user.getAuthMethods('userId', {
  includeWithoutDomain: true,
  domain: 'localhost',
})
console.log(authMethods)

`deleteUserTotp`

Deletes the TOTP configuration for a user.

await zitadelClient.user.totp.delete('userId')
console.log('User TOTP deleted')

`deleteUserU2fToken`

Deletes a U2F token for a user.

await zitadelClient.user.u2f.deleteToken({
  userId: 'userId',
  u2fId: 'u2fId',
})
console.log('User U2F token deleted')

`deleteUserOtpSms`

Deletes the OTP SMS configuration for a user.

await zitadelClient.user.otp.deleteOtpSms('userId')
console.log('User OTP SMS deleted')

`deleteUserOtpEmail`

Deletes the OTP Email configuration for a user.

await zitadelClient.user.otp.deleteOtpEmail('userId')
console.log('User OTP Email deleted')

`getUserPasskeys`

Retrieves the list of WebAuthn passkeys for a user.

const passkeys = await zitadelClient.user.passkey.list('userId', {})
console.log(passkeys)

`registerUserPasskey`

Starts the registration of a WebAuthn passkey for a user.

const passkey = await zitadelClient.user.passkey.register('userId', {
  code: {
    id: 'codeId',
    code: 'code',
  },
  authenticator: 'UNSPECIFIED',
  domain: 'localhost',
})
console.log(passkey)

`registerUserPasskeyLink`

Creates a registration link for a WebAuthn passkey for a user.

const passkeyLink = await zitadelClient.user.passkey.createRegistrationLink('userId', {
  returnCode: {},
})
console.log(passkeyLink)

`deleteRegisteredUserPasskey`

Deletes a registered WebAuthn passkey for a user.

await zitadelClient.user.passkey.delete({
  userId: 'userId',
  passkeyId: 'passkeyId',
})
console.log('User passkey deleted')

`getUserPermissions`

Retrieves the permissions of a user.

const permissions = await zitadelClient.user.getPermissions('userId', {
  query: {
    offset: '0',
    limit: 100,
    asc: true,
  },
  queries: [
    {
      iamQuery: {
        iam: true,
      },
    },
  ],
}, 'organizationId')
console.log(permissions)

License

This project is licensed under the MIT License. See the LICENSE file for details.

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
.vscode		.vscode
src		src
test		test
.editorconfig		.editorconfig
.env		.env
.gitignore		.gitignore
.npmrc		.npmrc
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE.md		LICENSE.md
README.md		README.md
build.config.ts		build.config.ts
eslint.config.js		eslint.config.js
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
tsconfig.json		tsconfig.json

Latest commit

History

Folders and files

Repository files navigation

Zitadel Client @bdjawed/zitadel-client

Table of Contents

Installation

Usage

Client Initialization

Methods

getUserInfo

createOrganization

deleteOrganization

createHumanUser

createMachineUser

createMachineUserKey

getMachineUserKeyById

getMachineUserKeys

userDeactivate

userReactivate

userLock

userUnlock

createMachineUserPAT

getMachineUserPAT

getMachineUserPATsList

deleteMachineUserPAT

getUserIDPsList

deleteMachineUserKey

createProject

createAppApi

deleteAppApi

createAppApiClientSecret

createAppOidc

updateLoginSettings

getLoginSettings

getUserById

deleteUserById

getUserByLoginName

usersSearch

getUserHistory

isUserUnique

getMetadataByKey

deleteMetadataByKey

createMetadataByKey

deleteBulkMetadataByKey

createBulkMetadataByKey

userMetadataSearch

deleteUserAvatar

updateMachineUser

updateHumanUser

deleteMachineUserSecret

createMachineUserSecret

createUserEmail

deleteUserPhone

createUserPhone

createUserPassword

createUserPasswordResetCode

resendUserEmailVerificationCode

resendUserPhoneVerificationCode

getUserAuthMethods

deleteUserTotp

deleteUserU2fToken

deleteUserOtpSms

deleteUserOtpEmail

getUserPasskeys

registerUserPasskey

registerUserPasskeyLink

deleteRegisteredUserPasskey

getUserPermissions