NAME
WWW::Zitadel::Management - Client for Zitadel Management API v1
VERSION
version 0.001
SYNOPSIS
use WWW::Zitadel::Management;
my $mgmt = WWW::Zitadel::Management->new(
base_url => 'https://zitadel.example.com',
token => $personal_access_token,
);
# Human users
my $users = $mgmt->list_users(limit => 50);
my $user = $mgmt->create_human_user(
user_name => 'alice',
first_name => 'Alice',
last_name => 'Smith',
email => 'alice@example.com',
);
my $info = $mgmt->get_user($user_id);
$mgmt->deactivate_user($user_id);
$mgmt->delete_user($user_id);
# Service (machine) users
my $svc = $mgmt->create_service_user(
user_name => 'ci-bot',
name => 'CI Bot',
);
my $key = $mgmt->add_machine_key($svc->{userId});
my $keys = $mgmt->list_machine_keys($svc->{userId});
$mgmt->remove_machine_key($svc->{userId}, $key->{keyId});
# Password management
$mgmt->set_password($user_id, password => 's3cr3t!');
$mgmt->request_password_reset($user_id);
# User metadata
$mgmt->set_user_metadata($user_id, 'department', 'engineering');
my $meta = $mgmt->get_user_metadata($user_id, 'department');
my $all = $mgmt->list_user_metadata($user_id);
# Projects
my $projects = $mgmt->list_projects;
my $project = $mgmt->create_project(name => 'My App');
# OIDC Applications
my $app = $mgmt->create_oidc_app($project_id,
name => 'Web Client',
redirect_uris => ['https://app.example.com/callback'],
);
$mgmt->update_oidc_app($project_id, $app_id,
redirect_uris => ['https://app.example.com/callback', 'https://app.example.com/silent'],
);
# Organizations
my $orgs = $mgmt->list_orgs;
$mgmt->update_org(name => 'Acme Corp');
$mgmt->deactivate_org;
# Roles
$mgmt->add_project_role($project_id,
role_key => 'admin',
display_name => 'Administrator',
);
# User Grants (assign roles)
$mgmt->create_user_grant(
user_id => $user_id,
project_id => $project_id,
role_keys => ['admin'],
);
# Identity Providers
my $idp = $mgmt->create_oidc_idp(
name => 'Google',
client_id => $client_id,
client_secret => $client_secret,
issuer => 'https://accounts.google.com',
);
$mgmt->activate_idp($idp->{idp}{id});
my $idps = $mgmt->list_idps;DESCRIPTION
Client for the Zitadel Management API v1. Authenticates with a Personal Access Token (PAT) and provides methods for managing users, service users, projects, OIDC applications, organizations, roles, and user grants.
All list_* methods accept offset, limit, and queries parameters. The queries parameter takes Zitadel's native query filter format — an arrayref of query objects, for example:
queries => [
{ displayNameQuery => { displayName => 'alice', method => 'TEXT_QUERY_METHOD_CONTAINS' } }
]See the ZITADEL Management API docs for the full query syntax per resource type.
Errors are thrown as WWW::Zitadel::Error subclass objects. Because they stringify to their message, existing eval/$@ string-matching patterns continue to work. For typed dispatch, check $@->isa('WWW::Zitadel::Error::API') etc.
base_url
Required. The Zitadel instance URL, e.g. https://zitadel.example.com. Must not be empty.
token
Required. Personal Access Token for authenticating with the Management API.
ua
Optional LWP::UserAgent instance. Provide a shared instance to reuse HTTP connections across both OIDC and Management clients:
my $ua = LWP::UserAgent->new(timeout => 30);
my $oidc = WWW::Zitadel::OIDC->new(issuer => $issuer, ua => $ua);
my $mgmt = WWW::Zitadel::Management->new(
base_url => $issuer,
token => $pat,
ua => $ua,
);list_users
get_user
create_human_user
update_user
deactivate_user
reactivate_user
delete_user
Human user CRUD operations. create_human_user requires user_name, first_name, last_name, and email.
create_service_user
list_service_users
get_service_user
delete_service_user
Machine/service user operations. create_service_user requires user_name and name. list_service_users automatically filters to machine-type users.
add_machine_key
list_machine_keys
remove_machine_key
Manage JWT authentication keys for a service user. add_machine_key accepts an optional type (default KEY_TYPE_JSON) and expiration_date.
set_password
request_password_reset
Password operations. set_password requires user_id and password.
set_user_metadata
get_user_metadata
list_user_metadata
Key/value metadata attached to a user. Values are base64-encoded as required by the ZITADEL API. set_user_metadata($user_id, $key, $value).
list_projects
get_project
create_project
update_project
delete_project
Project CRUD operations. create_project requires name.
list_apps
get_app
create_oidc_app
update_oidc_app
delete_app
OIDC application management within a project. create_oidc_app requires project_id, name, and redirect_uris.
update_oidc_app accepts the same snake_case keys as create_oidc_app: redirect_uris, response_types, grant_types, app_type, auth_method, post_logout_uris, dev_mode, access_token_type, id_token_role_assertion, additional_origins.
get_org
Returns the current organization of the authenticated user.
create_org
list_orgs
update_org
deactivate_org
Organization operations. create_org and update_org require name.
add_project_role
list_project_roles
Manage project roles. add_project_role requires project_id and role_key.
create_user_grant
list_user_grants
Assign roles to users. create_user_grant requires user_id, project_id, and role_keys (arrayref).
list_idps
get_idp
create_oidc_idp
update_idp
delete_idp
activate_idp
deactivate_idp
Identity provider management. create_oidc_idp requires name, client_id, client_secret, and issuer. Optional: scopes (default ["openid","profile","email"]), display_name_mapping, username_mapping, auto_register.
SEE ALSO
WWW::Zitadel, WWW::Zitadel::OIDC, WWW::Zitadel::Error
SUPPORT
Issues
Please report bugs and feature requests on GitHub at https://github.com/Getty/p5-www-zitadel/issues.
CONTRIBUTING
Contributions are welcome! Please fork the repository and submit a pull request.
AUTHOR
Torsten Raudssus <torsten@raudssus.de>
COPYRIGHT AND LICENSE
This software is copyright (c) 2026 by Torsten Raudssus.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.