zitadel-client 4.1.0.beta.11 → 4.1.0.beta.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 79e492c7af7e1aab9fcd95807b1a796f6ada6044d00fcdc35c3b43222c6f70de
-  data.tar.gz: 626804c4543a8af3656aa0b9b18df3cd2dbdc5e4730d08a0927c7e61fd246763
+  metadata.gz: 80b99719c332eacba3f9dfda861860033c67f1cc0864a9cdf01606bc9b042bc5
+  data.tar.gz: 8df3848854d1d8b66d0cd36ff4803a43d3b48b03d97c16f7fd0ede5978d75099
 SHA512:
-  metadata.gz: 7e6338a7155c80e9fff2f0cac83dc62e876de0cefdefbb131cddc8a41531d577a20d3236ce6c2d73fa9f69953d7fb5d191dd2d3274a74b0fc9caa925def571b1
-  data.tar.gz: 94527eb37dd943ec99651529f6ac798b91419faf9a06046eac42c7c54d50248b355df40d466c8b1fbc0715942906fe5f6bd14af7003633184d92bf838aa46154
+  metadata.gz: 7eb3b8f2e95066c5fd89e28419bb4d98e40b6829651ff1c276a4a230affdb6c8422f7be4fb7c66eea19fb137eb9e7ff95b324c37339b91b45b788c570129e2d8
+  data.tar.gz: 93208352051b9a5b31a58c78d2cc684a6a1dc3be4cf64b635447b07f4902cb08c37e602715df0fb2c5e87045ae2c49824941f87ff8adb0b85ceaf8a1c7775737

data/README.md

@@ -194,22 +194,99 @@ environment and security requirements. For more details, please refer to the
 ### Debugging
 
 The SDK supports debug logging, which can be enabled for troubleshooting
-and debugging purposes. You can enable debug logging by setting the `debug`
-flag to `true` when initializing the `Zitadel` client, like this:
+and debugging purposes. You can enable debug logging by setting `debugging`
+to `true` via the configuration block when initializing the `Zitadel` client:
 
 ```ruby
-zitadel = zitadel.Zitadel("your-zitadel-base-url", 'your-valid-token', lambda config: config.debug = True)
+zitadel = Zitadel::Client::Zitadel.with_access_token(
+  'your-zitadel-base-url',
+  'your-valid-token'
+) do |config|
+  config.debugging = true
+end
 ```
 
 When enabled, the SDK will log additional information, such as HTTP request
 and response details, which can be useful for identifying issues in the
 integration or troubleshooting unexpected behavior.
 
+## Advanced Configuration
+
+The SDK provides a `TransportOptions` object that allows you to customise
+the underlying HTTP transport used for both OpenID discovery and API calls.
+
+### Disabling TLS Verification
+
+In development or testing environments with self-signed certificates, you can
+disable TLS verification entirely:
+
+```ruby
+options = Zitadel::Client::TransportOptions.new(insecure: true)
+
+zitadel = Zitadel::Client::Zitadel.with_client_credentials(
+  'https://your-instance.zitadel.cloud',
+  'client-id',
+  'client-secret',
+  transport_options: options
+)
+```
+
+### Using a Custom CA Certificate
+
+If your Zitadel instance uses a certificate signed by a private CA, you can
+provide the path to the CA certificate in PEM format:
+
+```ruby
+options = Zitadel::Client::TransportOptions.new(ca_cert_path: '/path/to/ca.pem')
+
+zitadel = Zitadel::Client::Zitadel.with_client_credentials(
+  'https://your-instance.zitadel.cloud',
+  'client-id',
+  'client-secret',
+  transport_options: options
+)
+```
+
+### Custom Default Headers
+
+You can attach default headers to every outgoing request. This is useful for
+custom routing or tracing headers:
+
+```ruby
+options = Zitadel::Client::TransportOptions.new(
+  default_headers: { 'X-Custom-Header' => 'my-value' }
+)
+
+zitadel = Zitadel::Client::Zitadel.with_client_credentials(
+  'https://your-instance.zitadel.cloud',
+  'client-id',
+  'client-secret',
+  transport_options: options
+)
+```
+
+### Proxy Configuration
+
+If your environment requires routing traffic through an HTTP proxy, you can
+specify the proxy URL. To authenticate with the proxy, embed the credentials
+directly in the URL:
+
+```ruby
+options = Zitadel::Client::TransportOptions.new(proxy_url: 'http://user:pass@proxy:8080')
+
+zitadel = Zitadel::Client::Zitadel.with_client_credentials(
+  'https://your-instance.zitadel.cloud',
+  'client-id',
+  'client-secret',
+  transport_options: options
+)
+```
+
 ## Design and Dependencies
 
 This SDK is designed to be lean and efficient, focusing on providing a
 streamlined way to interact with the Zitadel API. It relies on the commonly used
-urllib3 HTTP transport for making requests, which ensures that
+Typhoeus HTTP library for making requests, which ensures that
 the SDK integrates well with other libraries and provides flexibility
 in terms of request handling and error management.
 

data/lib/zitadel/client/api_client.rb

@@ -48,7 +48,7 @@ module Zitadel
         @default_headers = {
           'Content-Type' => 'application/json',
           'User-Agent' => config.user_agent
-        }
+        }.merge(config.default_headers || {})
       end
 
       # noinspection RubyClassVariableUsageInspection,RbsMissingTypeSignature
@@ -114,6 +114,9 @@ module Zitadel
         # set custom cert, if provided
         req_opts[:cainfo] = @config.ssl_ca_cert if @config.ssl_ca_cert
 
+        # set proxy, if provided
+        req_opts[:proxy] = @config.proxy_url if @config.proxy_url
+
         if %i[post patch put delete].include?(http_method)
           req_body = build_request_body(header_params, form_params, opts[:body])
           req_opts.update body: req_body

data/lib/zitadel/client/auth/authenticator.rb

@@ -56,9 +56,12 @@ module Zitadel
         # Initializes the OAuthAuthenticatorBuilder with a given host.
         #
         # @param host [String] the base URL for the OAuth provider.
+        # @param transport_options [TransportOptions, nil] Optional transport options for TLS, proxy, and headers.
         #
-        def initialize(host)
-          @open_id = OpenId.new(host)
+        def initialize(host, transport_options: nil)
+          transport_options ||= TransportOptions.defaults
+          @transport_options = transport_options
+          @open_id = OpenId.new(host, transport_options: transport_options)
           @auth_scopes = Set.new(%w[openid urn:zitadel:iam:org:project:id:zitadel:aud])
         end
 

data/lib/zitadel/client/auth/client_credentials_authenticator.rb

@@ -11,12 +11,18 @@ module Zitadel
         # @param client_id [String] The OAuth client identifier.
         # @param client_secret [String] The OAuth client secret.
         # @param auth_scopes [Set<String>] The scope(s) for the token request.
-        def initialize(open_id, client_id, client_secret, auth_scopes)
+        # @param transport_options [TransportOptions, nil] Optional transport options for TLS, proxy, and headers.
+        def initialize(open_id, client_id, client_secret, auth_scopes, transport_options: nil)
+          transport_options ||= TransportOptions.defaults
+
+          conn_opts = transport_options.to_connection_opts
+
           # noinspection RubyArgCount
           super(open_id, auth_scopes, OAuth2::Client.new(client_id, client_secret, {
                                                            site: open_id.host_endpoint,
-                                                           token_url: open_id.token_endpoint
-                                                         }))
+                                                           token_url: open_id.token_endpoint,
+                                                           connection_opts: conn_opts
+                                                         }), transport_options: transport_options)
         end
 
         # Returns a new builder for constructing a ClientCredentialsAuthenticator.
@@ -24,9 +30,11 @@ module Zitadel
         # @param host [String] The OAuth provider's base URL.
         # @param client_id [String] The OAuth client identifier.
         # @param client_secret [String] The OAuth client secret.
+        # @param transport_options [TransportOptions, nil] Optional transport options for TLS, proxy, and headers.
         # @return [ClientCredentialsAuthenticatorBuilder] A builder instance.
-        def self.builder(host, client_id, client_secret)
-          ClientCredentialsAuthenticatorBuilder.new(host, client_id, client_secret)
+        def self.builder(host, client_id, client_secret, transport_options: nil)
+          ClientCredentialsAuthenticatorBuilder.new(host, client_id, client_secret,
+                                                    transport_options: transport_options)
         end
 
         protected
@@ -45,9 +53,10 @@ module Zitadel
           # @param host [String] The OAuth provider's base URL.
           # @param client_id [String] The OAuth client identifier.
           # @param client_secret [String] The OAuth client secret.
-          def initialize(host, client_id, client_secret)
+          # @param transport_options [TransportOptions, nil] Optional transport options for TLS, proxy, and headers.
+          def initialize(host, client_id, client_secret, transport_options: nil)
             # noinspection RubyArgCount
-            super(host)
+            super(host, transport_options: transport_options)
             @client_id = client_id
             @client_secret = client_secret
           end
@@ -56,7 +65,8 @@ module Zitadel
           #
           # @return [ClientCredentialsAuthenticator] A configured instance.
           def build
-            ClientCredentialsAuthenticator.new(open_id, @client_id, @client_secret, auth_scopes)
+            ClientCredentialsAuthenticator.new(open_id, @client_id, @client_secret, auth_scopes,
+                                               transport_options: @transport_options)
           end
         end
       end

data/lib/zitadel/client/auth/o_auth_authenticator.rb

@@ -25,11 +25,14 @@ module Zitadel
         # Constructs an OAuthAuthenticator.
         #
         # @param open_id [OpenId] An object that must implement `get_host_endpoint` and `get_token_endpoint`.
-        # @param auth_session [OAuth2Session] The OAuth2Session instance used for token requests.
+        # @param auth_scopes [Set<String>] The scope(s) for the token request.
+        # @param auth_session [OAuth2::Client] The OAuth2 client instance used for token requests.
+        # @param transport_options [TransportOptions, nil] Optional transport options for TLS, proxy, and headers.
         #
-        def initialize(open_id, auth_scopes, auth_session)
+        def initialize(open_id, auth_scopes, auth_session, transport_options: nil)
           super(open_id.host_endpoint)
           @open_id = open_id
+          @transport_options = transport_options || TransportOptions.defaults
           @token = nil
           @auth_session = auth_session
           @auth_scopes = auth_scopes.to_a.join(' ')

data/lib/zitadel/client/auth/open_id.rb

@@ -3,6 +3,7 @@
 require 'json'
 require 'uri'
 require 'net/http'
+require 'openssl'
 
 module Zitadel
   module Client
@@ -20,16 +21,38 @@ module Zitadel
         # Initializes a new OpenId instance.
         #
         # @param hostname [String] the hostname for the OpenID provider.
+        # @param transport_options [TransportOptions, nil] Optional transport options for TLS, proxy, and headers.
         # @raise [RuntimeError] if the OpenID configuration cannot be fetched or the token_endpoint is missing.
         #
         # noinspection HttpUrlsUsage
-        def initialize(hostname)
+        # rubocop:disable Metrics/AbcSize, Metrics/MethodLength, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+        def initialize(hostname, transport_options: nil)
+          transport_options ||= TransportOptions.defaults
           hostname = "https://#{hostname}" unless hostname.start_with?('http://', 'https://')
           @host_endpoint = hostname
           well_known_url = self.class.build_well_known_url(hostname)
 
           uri = URI.parse(well_known_url)
-          response = Net::HTTP.get_response(uri)
+          http = if transport_options.proxy_url
+                   proxy_uri = URI.parse(transport_options.proxy_url)
+                   Net::HTTP.new(uri.host.to_s, uri.port, proxy_uri.host, proxy_uri.port,
+                                 proxy_uri.user, proxy_uri.password)
+                 else
+                   Net::HTTP.new(uri.host.to_s, uri.port)
+                 end
+          http.use_ssl = (uri.scheme == 'https')
+          if transport_options.insecure
+            http.verify_mode = OpenSSL::SSL::VERIFY_NONE
+          elsif transport_options.ca_cert_path
+            store = OpenSSL::X509::Store.new
+            store.set_default_paths
+            store.add_file(transport_options.ca_cert_path)
+            http.cert_store = store
+            http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+          end
+          request = Net::HTTP::Get.new(uri)
+          transport_options.default_headers.each { |k, v| request[k] = v }
+          response = http.request(request)
           raise "Failed to fetch OpenID configuration: HTTP #{response.code}" unless response.code.to_i == 200
 
           config = JSON.parse(response.body)
@@ -38,6 +61,7 @@ module Zitadel
 
           @token_endpoint = token_endpoint
         end
+        # rubocop:enable Metrics/AbcSize, Metrics/MethodLength, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
 
         ##
         # Builds the well-known OpenID configuration URL for the given hostname.

data/lib/zitadel/client/auth/web_token_authenticator.rb

@@ -25,14 +25,20 @@ module Zitadel
         # @param jwt_lifetime [Integer] Lifetime of the JWT in seconds (default 3600 seconds).
         # @param jwt_algorithm [String] The JWT signing algorithm (default "RS256").
         # @param key_id [String, nil] Optional key identifier for the JWT header (default: nil).
-        # rubocop:disable Metrics/ParameterLists,Metrics/MethodLength
+        # @param transport_options [TransportOptions, nil] Optional transport options for TLS, proxy, and headers.
+        # rubocop:disable Metrics/ParameterLists, Metrics/MethodLength
         def initialize(open_id, auth_scopes, jwt_issuer, jwt_subject, jwt_audience, private_key,
-                       jwt_lifetime: 3600, jwt_algorithm: 'RS256', key_id: nil)
+                       jwt_lifetime: 3600, jwt_algorithm: 'RS256', key_id: nil, transport_options: nil)
+          transport_options ||= TransportOptions.defaults
+
+          conn_opts = transport_options.to_connection_opts
+
           # noinspection RubyArgCount,RubyMismatchedArgumentType
           super(open_id, auth_scopes, OAuth2::Client.new('zitadel', 'zitadel', {
                                                            site: open_id.host_endpoint,
-                                                           token_url: open_id.token_endpoint
-                                                         }))
+                                                           token_url: open_id.token_endpoint,
+                                                           connection_opts: conn_opts
+                                                         }), transport_options: transport_options)
           @jwt_issuer = jwt_issuer
           @jwt_subject = jwt_subject
           @jwt_audience = jwt_audience
@@ -47,7 +53,7 @@ module Zitadel
                          end
         end
 
-        # rubocop:enable Metrics/ParameterLists,Metrics/MethodLength
+        # rubocop:enable Metrics/ParameterLists, Metrics/MethodLength
 
         # Creates a WebTokenAuthenticator instance from a JSON configuration file.
         #
@@ -62,9 +68,11 @@ module Zitadel
         #
         # @param host [String] Base URL for the API endpoints.
         # @param json_path [String] File path to the JSON configuration file.
+        # @param transport_options [TransportOptions, nil] Optional transport options for TLS, proxy, and headers.
         # @return [WebTokenAuthenticator] A new instance of WebTokenAuthenticator.
         # @raise [RuntimeError] If the file cannot be read, the JSON is invalid, or required keys are missing.
-        def self.from_json(host, json_path)
+        # rubocop:disable Metrics/MethodLength
+        def self.from_json(host, json_path, transport_options: nil)
           config = JSON.parse(File.read(json_path))
         rescue Errno::ENOENT => e
           raise "Unable to read JSON file at #{json_path}: #{e.message}"
@@ -76,17 +84,21 @@ module Zitadel
           user_id, private_key, key_id = config.values_at('userId', 'key', 'keyId')
           raise "Missing required keys 'userId', 'keyId' or 'key'" unless user_id && key_id && private_key
 
-          WebTokenAuthenticator.builder(host, user_id, private_key).key_identifier(key_id).build
+          WebTokenAuthenticator.builder(host, user_id, private_key, transport_options: transport_options)
+                               .key_identifier(key_id).build
         end
+        # rubocop:enable Metrics/MethodLength
 
         # Returns a builder for constructing a WebTokenAuthenticator.
         #
         # @param host [String] The base URL for the OAuth provider.
         # @param user_id [String] The user identifier (used as both the issuer and subject).
         # @param private_key [String] The private key used to sign the JWT.
+        # @param transport_options [TransportOptions, nil] Optional transport options for TLS, proxy, and headers.
         # @return [WebTokenAuthenticatorBuilder] A builder instance.
-        def self.builder(host, user_id, private_key)
-          WebTokenAuthenticatorBuilder.new(host, user_id, user_id, host, private_key)
+        def self.builder(host, user_id, private_key, transport_options: nil)
+          WebTokenAuthenticatorBuilder.new(host, user_id, user_id, host, private_key,
+                                           transport_options: transport_options)
         end
 
         protected
@@ -130,15 +142,18 @@ module Zitadel
           # @param jwt_subject [String] The subject claim for the JWT.
           # @param jwt_audience [String] The audience claim for the JWT.
           # @param private_key [String] The PEM-formatted private key used for signing the JWT.
-          def initialize(host, jwt_issuer, jwt_subject, jwt_audience, private_key)
+          # @param transport_options [TransportOptions, nil] Optional transport options for TLS, proxy, and headers.
+          # rubocop:disable Metrics/ParameterLists
+          def initialize(host, jwt_issuer, jwt_subject, jwt_audience, private_key, transport_options: nil)
             # noinspection RubyArgCount
-            super(host)
+            super(host, transport_options: transport_options)
             @jwt_issuer = jwt_issuer
             @jwt_subject = jwt_subject
             @jwt_audience = jwt_audience
             @private_key = private_key
             @jwt_lifetime = 3600
           end
+          # rubocop:enable Metrics/ParameterLists
 
           # Sets the JWT token lifetime in seconds.
           #
@@ -159,7 +174,8 @@ module Zitadel
           # @return [WebTokenAuthenticator] A configured instance.
           def build
             WebTokenAuthenticator.new(open_id, auth_scopes, @jwt_issuer, @jwt_subject, @jwt_audience,
-                                      @private_key, jwt_lifetime: @jwt_lifetime, key_id: @key_id)
+                                      @private_key, jwt_lifetime: @jwt_lifetime, key_id: @key_id,
+                                                    transport_options: @transport_options)
           end
         end
       end

data/lib/zitadel/client/configuration.rb

@@ -149,6 +149,24 @@ module Zitadel
       # @return [String, nil]
       attr_accessor :user_agent
 
+      ##
+      # Additional headers to include in every HTTP request.
+      #
+      # These headers are merged with the default headers set by the API client.
+      # Defaults to an empty hash.
+      #
+      # @return [Hash{String => String}]
+      attr_accessor :default_headers
+
+      ##
+      # Proxy URL to use for HTTP requests.
+      #
+      # When set, all HTTP requests will be routed through the specified proxy.
+      # The URL should include the scheme, host, and port (e.g., "http://proxy:8080").
+      #
+      # @return [String, nil]
+      attr_accessor :proxy_url
+
       # rubocop:disable Metrics/MethodLength
       def initialize(authenticator = Auth::NoAuthAuthenticator.new)
         @authenticator = authenticator
@@ -157,6 +175,8 @@ module Zitadel
         @verify_ssl_host = true
         @cert_file = nil
         @key_file = nil
+        @default_headers = {}
+        @proxy_url = nil
         @timeout = 0
         @params_encoding = nil
         @debugging = false

data/lib/zitadel/client/transport_options.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require 'openssl'
+
+module Zitadel
+  module Client
+    # Immutable transport options for configuring HTTP connections.
+    class TransportOptions
+      # @return [Hash{String => String}] Default HTTP headers sent to the origin server with every request.
+      attr_reader :default_headers
+
+      # @return [String, nil] Path to a custom CA certificate file for TLS verification.
+      attr_reader :ca_cert_path
+
+      # @return [Boolean] Whether to disable TLS certificate verification.
+      attr_reader :insecure
+
+      # @return [String, nil] Proxy URL for HTTP connections.
+      attr_reader :proxy_url
+
+      # Creates a new TransportOptions instance.
+      #
+      # @param default_headers [Hash{String => String}] Default HTTP headers sent to the origin server with every request.
+      # @param ca_cert_path [String, nil] Path to a custom CA certificate file for TLS verification.
+      # @param insecure [Boolean] Whether to disable TLS certificate verification.
+      # @param proxy_url [String, nil] Proxy URL for HTTP connections.
+      # @return [TransportOptions] an immutable transport options instance.
+      def initialize(default_headers: {}, ca_cert_path: nil, insecure: false, proxy_url: nil)
+        @default_headers = default_headers.dup.freeze
+        @ca_cert_path = ca_cert_path&.dup&.freeze
+        @insecure = insecure
+        @proxy_url = proxy_url&.dup&.freeze
+        freeze
+      end
+
+      # Returns a TransportOptions instance with all default values.
+      #
+      # @return [TransportOptions] a default transport options instance.
+      def self.defaults
+        new
+      end
+
+      # Builds Faraday connection options from these transport options.
+      #
+      # @return [Hash] connection options for OAuth2::Client
+      # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+      def to_connection_opts
+        opts = {}
+        if insecure
+          opts[:ssl] = { verify: false }
+        elsif ca_cert_path
+          store = OpenSSL::X509::Store.new
+          store.set_default_paths
+          store.add_file(ca_cert_path)
+          opts[:ssl] = { cert_store: store, verify: true }
+        end
+        opts[:proxy] = proxy_url if proxy_url
+        opts[:headers] = default_headers.dup if default_headers.any?
+        opts
+      end
+      # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
+    end
+  end
+end

data/lib/zitadel/client/version.rb

@@ -2,6 +2,6 @@
 
 module Zitadel
   module Client
-    VERSION = '4.1.0.beta.11'
+    VERSION = '4.1.0.beta.12'
   end
 end

data/lib/zitadel/client/zitadel.rb

@@ -7,7 +7,7 @@ module Zitadel
     # Initializes and configures the SDK with the provided authentication strategy.
     # Sets up service APIs for interacting with various Zitadel features.
     # noinspection RubyTooManyInstanceVariablesInspection
-    class Zitadel
+    class Zitadel # rubocop:disable Metrics/ClassLength
       attr_reader :features,
                   :idps,
                   :instances,
@@ -90,10 +90,15 @@ module Zitadel
         #
         # @param host [String] API URL (e.g. "https://api.zitadel.example.com").
         # @param access_token [String] Personal Access Token for Bearer authentication.
-        # @return [Zitadel] SDK client configured with PAT authentication.
+        # @param transport_options [TransportOptions, nil] Optional transport options for TLS, proxy, and headers.
+        # @return [Zitadel] Configured Zitadel client instance.
         # @see https://zitadel.com/docs/guides/integrate/service-users/personal-access-token
-        def with_access_token(host, access_token)
-          new(Auth::PersonalAccessTokenAuthenticator.new(host, access_token))
+        def with_access_token(host, access_token, transport_options: nil, &block)
+          resolved = transport_options || TransportOptions.defaults
+          new(Auth::PersonalAccessTokenAuthenticator.new(host, access_token)) do |config|
+            apply_transport_options(config, resolved)
+            block&.call(config)
+          end
         end
 
         # Initialize the SDK using OAuth2 Client Credentials flow.
@@ -101,27 +106,50 @@ module Zitadel
         # @param host [String] API URL.
         # @param client_id [String] OAuth2 client identifier.
         # @param client_secret [String] OAuth2 client secret.
-        # @return [Zitadel] SDK client with automatic token acquisition & refresh.
+        # @param transport_options [TransportOptions, nil] Optional transport options for TLS, proxy, and headers.
+        # @return [Zitadel] Configured Zitadel client instance with token auto-refresh.
         # @see https://zitadel.com/docs/guides/integrate/service-users/client-credentials
-        def with_client_credentials(host, client_id, client_secret)
+        def with_client_credentials(host, client_id, client_secret, transport_options: nil, &block)
+          resolved = transport_options || TransportOptions.defaults
           new(
             Auth::ClientCredentialsAuthenticator
-              .builder(host, client_id, client_secret)
+              .builder(host, client_id, client_secret, transport_options: resolved)
               .build
-          )
+          ) do |config|
+            apply_transport_options(config, resolved)
+            block&.call(config)
+          end
         end
 
         # Initialize the SDK via Private Key JWT assertion.
         #
         # @param host [String] API URL.
         # @param key_file [String] Path to service account JSON/PEM key file.
-        # @return [Zitadel] SDK client using JWT assertion for secure, secret-less auth.
+        # @param transport_options [TransportOptions, nil] Optional transport options for TLS, proxy, and headers.
+        # @return [Zitadel] Configured Zitadel client instance using JWT assertion.
         # @see https://zitadel.com/docs/guides/integrate/service-users/private-key-jwt
-        def with_private_key(host, key_file)
-          new(Auth::WebTokenAuthenticator.from_json(host, key_file))
+        def with_private_key(host, key_file, transport_options: nil, &block)
+          resolved = transport_options || TransportOptions.defaults
+          new(Auth::WebTokenAuthenticator.from_json(host, key_file,
+                                                    transport_options: resolved)) do |config|
+            apply_transport_options(config, resolved)
+            block&.call(config)
+          end
         end
 
         # @!endgroup
+
+        private
+
+        def apply_transport_options(config, resolved)
+          config.default_headers = resolved.default_headers.dup
+          config.ssl_ca_cert = resolved.ca_cert_path if resolved.ca_cert_path
+          if resolved.insecure
+            config.verify_ssl = false
+            config.verify_ssl_host = false
+          end
+          config.proxy_url = resolved.proxy_url if resolved.proxy_url
+        end
       end
     end
   end

data/sig/lib/oauth2/oauth2.rbs

@@ -85,7 +85,7 @@ module OAuth2
   end
 
   class Client
-    def initialize: (String | nil, String | nil, Hash[Symbol, String]) -> void
+    def initialize: (String | nil, String | nil, Hash[Symbol, untyped]) -> void
 
     def fetch_token: (url: String, **untyped) -> AccessToken
 

data/sig/lib.rbs

@@ -132,6 +132,8 @@ module Zitadel
       attr_accessor cert_file: String?
       attr_accessor key_file: String?
       attr_accessor params_encoding: Symbol?
+      attr_accessor default_headers: Hash[String, String]
+      attr_accessor proxy_url: String?
 
       def self.default: () -> Configuration
 
@@ -202,6 +204,16 @@ module Zitadel
       def initialize: (Integer, Hash[String, Array[String]], String | Typhoeus::Response) -> void
     end
 
+    class TransportOptions
+      attr_reader default_headers: Hash[String, String]
+      attr_reader ca_cert_path: String?
+      attr_reader insecure: bool
+      attr_reader proxy_url: String?
+      def initialize: (?default_headers: Hash[String, String], ?ca_cert_path: String?, ?insecure: bool, ?proxy_url: String?) -> void
+      def self.defaults: -> TransportOptions
+      def to_connection_opts: -> Hash[Symbol, untyped]
+    end
+
     module Auth
 
       class Authenticator
@@ -217,17 +229,17 @@ module Zitadel
 
       class ClientCredentialsAuthenticator < OAuthAuthenticator
 
-        def initialize: (OpenId, String, String, Set[String]) -> void
+        def initialize: (OpenId, String, String, Set[String], ?transport_options: TransportOptions?) -> void
 
         def get_grant: (OAuth2::Client, String) -> OAuth2::AccessToken
 
-        def self.builder: (String, String, String) -> ClientCredentialsAuthenticatorBuilder
+        def self.builder: (String, String, String, ?transport_options: TransportOptions?) -> ClientCredentialsAuthenticatorBuilder
 
         class ClientCredentialsAuthenticatorBuilder < OAuthAuthenticatorBuilder
           @client_id: String
           @client_secret: String
 
-          def initialize: (String, String, String) -> void
+          def initialize: (String, String, String, ?transport_options: TransportOptions?) -> void
 
           def build: -> ClientCredentialsAuthenticator
         end
@@ -248,7 +260,7 @@ module Zitadel
         attr_reader open_id: OpenId
         attr_reader auth_scopes: Set[String]
 
-        def initialize: (String) -> void
+        def initialize: (String, ?transport_options: TransportOptions?) -> void
 
         def scopes: (*String) -> self
       end
@@ -259,8 +271,9 @@ module Zitadel
         @open_id: OpenId
         @token: OAuth2::AccessToken
         @auth_scopes: String
+        @transport_options: TransportOptions
 
-        def initialize: (OpenId, Set[String], OAuth2::Client) -> void
+        def initialize: (OpenId, Set[String], OAuth2::Client, ?transport_options: TransportOptions?) -> void
 
         def auth_token: () -> String
 
@@ -278,7 +291,7 @@ module Zitadel
         attr_accessor host_endpoint: String
         attr_accessor token_endpoint: String
 
-        def initialize: (String) -> void
+        def initialize: (String, ?transport_options: TransportOptions?) -> void
 
         def self.build_well_known_url: (String) -> String
       end
@@ -300,13 +313,13 @@ module Zitadel
         @key_id: String?
         @private_key: OpenSSL::PKey::RSA
 
-        def self.builder: (String, String, String) -> WebTokenAuthenticatorBuilder
+        def self.builder: (String, String, String, ?transport_options: TransportOptions?) -> WebTokenAuthenticatorBuilder
 
-        def self.from_json: (String, String) -> WebTokenAuthenticator
+        def self.from_json: (String, String, ?transport_options: TransportOptions?) -> WebTokenAuthenticator
 
         def get_grant: (OAuth2::Client, String) -> OAuth2::AccessToken
 
-        def initialize: (OpenId, Set[String], String, String, String, (String | OpenSSL::PKey::PKey), ?jwt_lifetime: Integer, ?jwt_algorithm: String, ?key_id: String?) -> void
+        def initialize: (OpenId, Set[String], String, String, String, (String | OpenSSL::PKey::PKey), ?jwt_lifetime: Integer, ?jwt_algorithm: String, ?key_id: String?, ?transport_options: TransportOptions?) -> void
 
         class WebTokenAuthenticatorBuilder < OAuthAuthenticatorBuilder
           @jwt_audience: String
@@ -316,7 +329,7 @@ module Zitadel
           @key_id: String
           @private_key: String
 
-          def initialize: (String, String, String, String, String) -> void
+          def initialize: (String, String, String, String, String, ?transport_options: TransportOptions?) -> void
 
           def build: -> WebTokenAuthenticator
 
@@ -329,11 +342,17 @@ module Zitadel
 
     class Zitadel
 
-      def self.with_access_token: (String, String) -> Zitadel
+      def self.with_access_token: (String, String, ?transport_options: TransportOptions?) ?{ (Configuration) -> void } -> Zitadel
+
+      def self.with_client_credentials: (String, String, String, ?transport_options: TransportOptions?) ?{ (Configuration) -> void } -> Zitadel
+
+      def self.with_private_key: (String, String, ?transport_options: TransportOptions?) ?{ (Configuration) -> void } -> Zitadel
+
+      private
 
-      def self.with_client_credentials: (String, String, String) -> Zitadel
+      def self.apply_transport_options: (Configuration, TransportOptions) -> void
 
-      def self.with_private_key: (String, String) -> Zitadel
+      public
 
       attr_reader configuration: Configuration
       attr_reader features: Api::FeatureServiceApi

metadata

@@ -1,15 +1,70 @@
 --- !ruby/object:Gem::Specification
 name: zitadel-client
 version: !ruby/object:Gem::Version
-  version: 4.1.0.beta.11
+  version: 4.1.0.beta.12
 platform: ruby
 authors:
 - Zitadel
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-03 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: cgi
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: date
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.4'
+- !ruby/object:Gem::Dependency
+  name: net-http
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.1'
 - !ruby/object:Gem::Dependency
   name: oauth2
   requirement: !ruby/object:Gem::Requirement
@@ -24,6 +79,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: tempfile
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: time
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.1'
 - !ruby/object:Gem::Dependency
   name: typhoeus
   requirement: !ruby/object:Gem::Requirement
@@ -44,6 +127,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 1.0.1
+- !ruby/object:Gem::Dependency
+  name: uri
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.10'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.10'
 - !ruby/object:Gem::Dependency
   name: warning
   requirement: !ruby/object:Gem::Requirement
@@ -1474,6 +1571,7 @@ files:
 - lib/zitadel/client/models/web_key_service_r_s_a_hasher.rb
 - lib/zitadel/client/models/web_key_service_state.rb
 - lib/zitadel/client/models/web_key_service_web_key.rb
+- lib/zitadel/client/transport_options.rb
 - lib/zitadel/client/utils/url_util.rb
 - lib/zitadel/client/version.rb
 - lib/zitadel/client/zitadel.rb
@@ -1489,7 +1587,6 @@ licenses:
 - Apache-2.0
 metadata:
   rubygems_mfa_required: 'true'
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -1500,12 +1597,11 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '3.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
-rubygems_version: 3.2.33
-signing_key:
+rubygems_version: 4.0.3
 specification_version: 4
 summary: Official Zitadel SDK for Ruby
 test_files: []