NAME
Net::Async::Zitadel::OIDC - Async OIDC client for Zitadel - token verification, JWKS, discovery
VERSION
version 0.001
SYNOPSIS
use IO::Async::Loop;
use Net::Async::Zitadel;
my $loop = IO::Async::Loop->new;
my $z = Net::Async::Zitadel->new(issuer => 'https://zitadel.example.com');
$loop->add($z);
# Async token verification
my $claims = $z->oidc->verify_token_f($access_token)->get;
# Async userinfo
my $user = $z->oidc->userinfo_f($access_token)->get;
# Async client credentials token
my $token = $z->oidc->client_credentials_token_f(
client_id => $id,
client_secret => $secret,
)->get;DESCRIPTION
Async OIDC client for Zitadel, built on Net::Async::HTTP and Future. All methods return Future objects (_f suffix convention).
Token verification automatically retries with a refreshed JWKS on failure, handling key rotation transparently. Concurrent JWKS refresh requests are coalesced: if a refresh is already in-flight, subsequent callers receive the same Future rather than triggering a second HTTP request.
issuer
Required. The Zitadel issuer URL. Must not be empty.
http
Required. A Net::Async::HTTP instance (typically shared from Net::Async::Zitadel).
discovery_f
Returns a Future resolving to the parsed OpenID Connect discovery document. Cached after first fetch.
jwks_f
Returns a Future resolving to the JSON Web Key Set. Cached after first fetch. Pass force_refresh => 1 to bypass the cache. Concurrent non-forced calls coalesce into the same in-flight request.
verify_token_f
my $f = $oidc->verify_token_f($jwt, %options);Returns a Future resolving to the decoded claims hashref. Automatically retries once with a fresh JWKS on verification failure (key rotation). Options: audience, verify_exp, verify_iat, verify_nbf, accepted_key_alg, no_retry.
userinfo_f
my $f = $oidc->userinfo_f($access_token);Returns a Future resolving to the UserInfo endpoint response.
introspect_f
my $f = $oidc->introspect_f($token,
client_id => $id,
client_secret => $secret,
);Returns a Future resolving to the token introspection response.
token_f
my $f = $oidc->token_f(grant_type => 'client_credentials', %params);Generic async token endpoint POST (form-encoded). Returns a Future.
client_credentials_token_f
Convenience wrapper for client_credentials grant.
refresh_token_f
Convenience wrapper for refresh_token grant.
exchange_authorization_code_f
Convenience wrapper for authorization_code grant.
discovery_ttl
How many seconds to cache the OpenID Connect discovery document before re-fetching. Default: 3600 (one hour). Set to 0 to disable caching.
jwks_ttl
How many seconds to cache the JSON Web Key Set before re-fetching. Default: 300 (five minutes). Set to 0 to disable caching.
SEE ALSO
Net::Async::Zitadel, WWW::Zitadel::OIDC, Crypt::JWT, Future
SUPPORT
Issues
Please report bugs and feature requests on GitHub at https://github.com/Getty/p5-net-async-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.