auth0 6.5.0 → 6.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0aef33bb7fb9dd8990a6f3a39622aba986b7a020907d8525990391d9deb71e0f
-  data.tar.gz: c90d04eb8ef0023be41b267547320b64ab259d651ddab120a42be278ee193285
+  metadata.gz: 7e787d64726dfd6bfb46857e1e1d68df5c06cf088d71c998da367a0e9487be9f
+  data.tar.gz: 59a2130de04ac2c65e6129979de443daae5bd0215c4eb4cafb0650b13bde9095
 SHA512:
-  metadata.gz: cc5b3db616d82d0dc6619e51da61abbb3455ceae6eec16869122cbfc88b8626aa66d9c57c6549ff5d9a1659691c8379527078d4e5f747e06f3688fbf28c8391c
-  data.tar.gz: 8d30725488a0cd575d8bc6fff7e740a8f17d8170e6871fade8e83a584e0b3f72b78b0059c83d2ba6e52901a4210bc1d1078f14c7e75baee87f7696e87a413701
+  metadata.gz: ed27130d281f1ff2cac53fa12d0eb1bb810b3f07c0ff73d89ef073725af9fbcb5e8796f4fabec90798e4aa23fefb94f96211551d5dc7d64aae8f72b3398d14f3
+  data.tar.gz: 184e6c27433b16e4e0fcbba7193ff3a758c0e2aaa5843d98495529394e1105267e369ef2b526b9c2135ab9e05e5778701cd9ab6bd4aab36bed58ab60bec3d470

data/.fern/metadata.json

@@ -1,5 +1,5 @@
 {
-  "cliVersion": "5.144.3",
+  "cliVersion": "5.166.0",
   "generatorName": "fernapi/fern-ruby-sdk",
   "generatorVersion": "1.24.1",
   "generatorConfig": {
@@ -10,9 +10,9 @@
     "offsetSemantics": "page-index",
     "useDefaultRequestParameterValues": true
   },
-  "originGitCommit": "275ad23d02d33d550693bc23ebae86dfa8ee7101",
+  "originGitCommit": "30874f917fa5eed3526d32a3bfd2ff024d36a4f4",
   "originGitCommitIsDirty": false,
   "invokedBy": "ci",
   "ciProvider": "github",
-  "sdkVersion": "6.4.1"
+  "sdkVersion": "6.5.1"
 }

data/.fern/replay.lock

@@ -1,64 +1,22 @@
 # DO NOT EDIT MANUALLY - Managed by Fern Replay
 version: "1.0"
 generations:
-  - commit_sha: 78ff190749feb3803b4e9629d57294e4b09d3ead
-    tree_hash: c3e180060dcea59de5c4290a242c66639e5cecff
-    timestamp: 2026-07-14T04:31:08.668Z
+  - commit_sha: 1af018d42213a5a5a4a5857b8ee326c968405184
+    tree_hash: 26cc3589bfbfef3bd26972743969ea67451c2a23
+    timestamp: 2026-10-27T11:22:31.372Z
     cli_version: unknown
     generator_versions: {}
-  - commit_sha: 6caf043a4469185ba0f690eb2da7c6889138f4d7
-    tree_hash: dbc1a9fac4f5566751f2760dc8e1191d47892bd5
-    timestamp: 2026-07-14T04:31:09.152Z
-    cli_version: unknown
-    generator_versions:
-      fernapi/fern-ruby-sdk: 1.13.1
-  - commit_sha: 428032101d1791fe97573af36427e664fe4e1e88
-    tree_hash: 231d5c443ba4120855bd439d858060fc178043cd
-    timestamp: 2026-07-15T09:11:13.405Z
-    cli_version: unknown
-    generator_versions:
-      fernapi/fern-ruby-sdk: 1.13.1
-  - commit_sha: d8a88028849ce519e8fdc20765c78e367f372110
-    tree_hash: 3e4eff170915344776a2c1e921a378a13c54afd1
-    timestamp: 2026-07-21T07:06:12.329Z
-    cli_version: unknown
-    generator_versions:
-      fernapi/fern-ruby-sdk: 1.17.8
-  - commit_sha: ff82f16a518e8ee51b23570ed1a303f3c070ff02
-    tree_hash: 6b4ba82c8dbe3556b6c8e7dd4f7c4d32671aa12a
-    timestamp: 2026-08-04T06:22:44.311Z
-    cli_version: unknown
-    generator_versions:
-      fernapi/fern-ruby-sdk: 1.17.8
-  - commit_sha: 1cfe82c679b6122773317ebd41bff24b09388b3d
-    tree_hash: a7034ef350a9bfaa17781b64316723f688b91e18
-    timestamp: 2026-08-19T06:07:50.024Z
-    cli_version: unknown
-    generator_versions:
-      fernapi/fern-ruby-sdk: 1.17.8
-  - commit_sha: 78116dc530cd08317c9323863f3127c2fdec29ee
-    tree_hash: d0d935e417bf22e33c1c1eb9c6c43371d35907c0
-    timestamp: 2026-09-02T09:27:17.154Z
-    cli_version: unknown
-    generator_versions:
-      fernapi/fern-ruby-sdk: 1.17.8
-  - commit_sha: 83074ed870797568e512cc7f0fb71dc679cdd7f4
-    tree_hash: cbc5c6ccd2dfd5be3b5d68f7bc45a51e62fa6704
-    timestamp: 2026-09-15T12:33:08.051Z
-    cli_version: unknown
-    generator_versions:
-      fernapi/fern-ruby-sdk: 1.24.1
-  - commit_sha: ddd12c1ca38e6c93db2c1d30e4194a2ecbca03ba
-    tree_hash: fa2bf11afbbd64aff874ac158dfaf67412ee73d7
-    timestamp: 2026-09-29T05:46:29.187Z
+  - commit_sha: 1f0cde99ca7fdddcfc5635a1f41bf51a7efe863c
+    tree_hash: 781e4e5affb287da31d3713a3f16811228a7ada7
+    timestamp: 2026-10-27T11:30:28.609Z
     cli_version: unknown
     generator_versions:
       fernapi/fern-ruby-sdk: 1.24.1
-  - commit_sha: 3ee763815dcd7a7a39f5c3c7c6bd40d4de0014d6
-    tree_hash: 0ce0997d753141426376e5ff1dcc183ea138c84e
-    timestamp: 2026-10-13T10:24:06.305Z
+  - commit_sha: c4b1c95e4e0668d2c42aaa0a4c5c5ab1e8a642f8
+    tree_hash: d37708b9770790ac5501ab5c8a3a038868cd45d1
+    timestamp: 2026-11-04T03:49:40.588Z
     cli_version: unknown
     generator_versions:
       fernapi/fern-ruby-sdk: 1.24.1
-current_generation: 3ee763815dcd7a7a39f5c3c7c6bd40d4de0014d6
+current_generation: c4b1c95e4e0668d2c42aaa0a4c5c5ab1e8a642f8
 patches: []

data/.version

@@ -1 +1 @@
-v6.5.0
+v6.6.0

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Change Log
 
+## [v6.6.0](https://github.com/auth0/ruby-auth0/tree/v6.6.0) (2026-11-04)
+[Full Changelog](https://github.com/auth0/ruby-auth0/compare/v6.5.0...v6.6.0)
+
+**Added**
+- feat!: add Portals, Client agent_id and agent subject claims, and wrap Consent Signing Keys list response [\#824](https://github.com/auth0/ruby-auth0/pull/824) ([fern-api[bot]](https://github.com/apps/fern-api))
+- feat: add Consent Signing Keys, OTP Settings, Resource Server type and Management tenant_domain, and remove Captcha Policies [\#821](https://github.com/auth0/ruby-auth0/pull/821) ([fern-api[bot]](https://github.com/apps/fern-api))
+- feat: expose Management API rate limit info via a client callback [\#774](https://github.com/auth0/ruby-auth0/pull/774) ([ProdigyTom](https://github.com/ProdigyTom))
+
 ## [v6.5.0](https://github.com/auth0/ruby-auth0/tree/v6.5.0) (2026-10-14)
 [Full Changelog](https://github.com/auth0/ruby-auth0/compare/v6.4.0...v6.5.0)
 

data/EXAMPLES.md

@@ -166,6 +166,26 @@ management.roles.create(name: 'admin', description: 'Administrator')
 management.organizations.list(take: 20)
 ```
 
+## Rate Limit Monitoring
+
+Pass a `rate_limit_handler` when building an `Auth0::Client` to observe Auth0's `x-ratelimit-*` headers, without changing the return value of your calls. It covers Management API calls and the Authentication API calls made through the client's HTTP layer (it is not available on `Auth0::Management` directly):
+
+```ruby
+client = Auth0::Client.new(
+  domain: ENV['AUTH0_RUBY_DOMAIN'],
+  client_id: ENV['AUTH0_RUBY_CLIENT_ID'],
+  client_secret: ENV['AUTH0_RUBY_CLIENT_SECRET'],
+  rate_limit_handler: lambda do |rate_limit|
+    # rate_limit.limit / rate_limit.remaining (Integers), rate_limit.reset (UTC Time)
+    Rails.logger.info("Auth0 rate limit: #{rate_limit.remaining}/#{rate_limit.limit}, resets at #{rate_limit.reset}")
+  end
+)
+
+client.users.get(id: 'auth0|123456') # handler fires with this response's rate limit
+```
+
+The handler is invoked on every response, including the `429`s that trigger an automatic retry. An error raised inside the handler is caught (and warned) so it never breaks the request.
+
 ## Organizations
 
 [Organizations](https://auth0.com/docs/organizations) is a set of features that provide better support for developers who build and maintain SaaS and Business-to-Business (B2B) applications.

data/README.md

@@ -104,6 +104,7 @@ client = Auth0::Client.new(
 | `management_timeout` | Float | Timeout in seconds for Management API calls. | `60` |
 | `management_max_retries` | Integer | Maximum retries for Management API calls. | `2` |
 | `management_additional_headers` | Hash | Additional HTTP headers for Management API calls. | `nil` |
+| `rate_limit_handler` | `#call` | Callback for [rate-limit monitoring](#rate-limit-monitoring). | `nil` |
 
 #### Accessing the Management Client Directly
 
@@ -283,6 +284,23 @@ client.users.list(
 )
 ```
 
+### Rate Limit Monitoring
+
+Auth0 returns `x-ratelimit-limit`, `x-ratelimit-remaining`, and `x-ratelimit-reset` headers on API responses. Pass a `rate_limit_handler` when building an `Auth0::Client` to be notified of this data, so you can monitor how close you are to the limit (for example, emit a metric and alert before you run out). It covers Management API calls and the Authentication API calls made through the client's HTTP layer (the JWKS fetch used by `validate_id_token` goes through a separate object and is not reported). It is not available on `Auth0::Management` directly.
+
+```ruby
+client = Auth0::Client.new(
+  domain: ENV['AUTH0_RUBY_DOMAIN'],
+  client_id: ENV['AUTH0_RUBY_CLIENT_ID'],
+  client_secret: ENV['AUTH0_RUBY_CLIENT_SECRET'],
+  rate_limit_handler: lambda do |rate_limit|
+    StatsD.gauge('auth0.rate_limit.remaining', rate_limit.remaining) if rate_limit.remaining
+  end
+)
+```
+
+The handler receives an object with `#limit`, `#remaining` (Integers), and `#reset` (a UTC `Time`). Each is `nil` when the corresponding header is absent or non-numeric. It is invoked on every response, including the `429`s that trigger an automatic retry, so you can observe the point at which the limit was reached. The return value of your API call is unchanged, and an exception raised inside the handler is caught (and warned) so it can never break a request.
+
 ### Errors
 
 Management API errors use the `Auth0::Errors` namespace:

data/examples/ruby-api/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ../..
   specs:
-    auth0 (6.5.0)
+    auth0 (6.6.0)
       addressable (~> 2.8)
       jwt (>= 2.7, < 4.0)
       rest-client (~> 2.1)

data/lib/auth0/attack_protection/brute_force_protection/types/update_brute_force_settings_request_content.rb

@@ -13,9 +13,9 @@ module Auth0
 
           field :mode, -> { Auth0::Types::BruteForceProtectionModeEnum }, optional: true, nullable: false
 
-          field :max_attempts, -> { Integer }, optional: true, nullable: false
-
           field :form_submission_mode, -> { Auth0::Types::BruteForceProtectionFormSubmissionModeEnum }, optional: true, nullable: false
+
+          field :max_attempts, -> { Integer }, optional: true, nullable: false
         end
       end
     end

data/lib/auth0/attack_protection/client.rb

@@ -30,11 +30,6 @@ module Auth0
         @captcha ||= Auth0::AttackProtection::Captcha::Client.new(client: @client)
       end
 
-      # @return [Auth0::CaptchaPolicies::Client]
-      def captcha_policies
-        @captcha_policies ||= Auth0::AttackProtection::CaptchaPolicies::Client.new(client: @client)
-      end
-
       # @return [Auth0::PhoneProviderProtection::Client]
       def phone_provider_protection
         @phone_provider_protection ||= Auth0::AttackProtection::PhoneProviderProtection::Client.new(client: @client)

data/lib/auth0/auth_client.rb

@@ -85,14 +85,39 @@ module Auth0
     def management
       current_token = get_token
       if @_management.nil? || @_management_token != current_token
-        @_management_token = current_token
         opts = { token: current_token, base_url: "#{@base_uri}/api/v2" }
         opts[:timeout] = @management_timeout if @management_timeout
         opts[:max_retries] = @management_max_retries if @management_max_retries
         opts[:headers] = @management_additional_headers if @management_additional_headers
-        @_management = Auth0::Management.new(**opts)
+        management = Auth0::Management.new(**opts)
+        # Attach before caching so a failed attach doesn't leave a handler-less
+        # management cached (the next call would then skip the rebuild).
+        attach_rate_limit_handler(management)
+        @_management = management
+        @_management_token = current_token
       end
       @_management
     end
+
+    private
+
+    # Attaches the configured rate limit handler to the management client's raw
+    # client. Fails loudly rather than silently skipping, so a future change to
+    # the generated client's internals surfaces instead of quietly disabling it.
+    # @param management [Auth0::Management]
+    # @return [void]
+    # @raise [Auth0::Exception] if the management client exposes no compatible raw client
+    def attach_rate_limit_handler(management)
+      return if @rate_limit_handler.nil?
+
+      raw_client = management.instance_variable_get(:@raw_client)
+      unless raw_client.respond_to?(:rate_limit_handler=)
+        raise Auth0::Exception,
+              "Unable to attach rate_limit_handler: the management client does not expose a compatible raw client. " \
+              "This likely means the ruby-auth0 internals changed. Please report it."
+      end
+
+      raw_client.rate_limit_handler = @rate_limit_handler
+    end
   end
 end

data/lib/auth0/client.rb

@@ -4,12 +4,20 @@ module Auth0
   class Management
     # @param token [String]
     # @param base_url [String, nil]
+    # @param tenant_domain [String, nil] Tenant domain, such as "example.auth0.com", used to build the base URL.
     # @param timeout [Float, nil] Request timeout in seconds.
-    # @param max_retries [Integer, nil] Maximum number of request retries.
+    # @param max_retries [Integer] Maximum number of request retries, defaults to 2.
     # @param headers [Hash, nil] Additional headers to include in requests.
     #
     # @return [void]
-    def initialize(token:, base_url: nil, timeout: nil, max_retries: nil, headers: nil)
+    def initialize(token:, base_url: nil, tenant_domain: nil, timeout: nil, max_retries: 2, headers: nil)
+      unless tenant_domain.nil?
+        environment_url_templates = {
+          Auth0::Environment::DEFAULT => "https://#{tenant_domain}/api/v2"
+        }
+        base_url = base_url.nil? ? "https://#{tenant_domain}/api/v2" : environment_url_templates.fetch(base_url, base_url)
+      end
+
       raw_client_opts = {
         base_url: base_url || Auth0::Environment::DEFAULT,
         headers: {
@@ -143,6 +151,11 @@ module Auth0
       @organizations ||= Auth0::Organizations::Client.new(client: @raw_client)
     end
 
+    # @return [Auth0::Portals::Client]
+    def portals
+      @portals ||= Auth0::Portals::Client.new(client: @raw_client)
+    end
+
     # @return [Auth0::Prompts::Client]
     def prompts
       @prompts ||= Auth0::Prompts::Client.new(client: @raw_client)

data/lib/auth0/clients/client.rb

@@ -54,6 +54,7 @@ module Auth0
       # @option params [Boolean, nil] :is_first_party
       # @option params [String, nil] :app_type
       # @option params [String, nil] :external_client_id
+      # @option params [String, nil] :agent_id
       # @option params [String, nil] :q
       #
       # @example
@@ -67,6 +68,7 @@ module Auth0
       #     is_first_party: true,
       #     app_type: "app_type",
       #     external_client_id: "external_client_id",
+      #     agent_id: "agent_id",
       #     q: "q"
       #   )
       #
@@ -83,6 +85,7 @@ module Auth0
         query_params["is_first_party"] = params[:is_first_party] if params.key?(:is_first_party)
         query_params["app_type"] = params[:app_type] if params.key?(:app_type)
         query_params["external_client_id"] = params[:external_client_id] if params.key?(:external_client_id)
+        query_params["agent_id"] = params[:agent_id] if params.key?(:agent_id)
         query_params["q"] = params[:q] if params.key?(:q)
 
         Auth0::Internal::OffsetItemIterator.new(

data/lib/auth0/clients/types/create_client_request_content.rb

@@ -122,6 +122,8 @@ module Auth0
 
         field :async_approval_notification_channels, -> { Internal::Types::Array[Auth0::Types::AsyncApprovalNotificationsChannelsEnum] }, optional: true, nullable: false
 
+        field :agent_id, -> { String }, optional: true, nullable: false
+
         field :oidc_support, -> { Auth0::Types::ClientOidcSupportPost }, optional: true, nullable: false
       end
     end

data/lib/auth0/clients/types/list_clients_request_parameters.rb

@@ -22,6 +22,8 @@ module Auth0
 
         field :external_client_id, -> { String }, optional: true, nullable: false
 
+        field :agent_id, -> { String }, optional: true, nullable: false
+
         field :q, -> { String }, optional: true, nullable: false
       end
     end

data/lib/auth0/clients/types/update_client_request_content.rb

@@ -124,6 +124,8 @@ module Auth0
 
         field :redirection_policy, -> { Auth0::Types::ClientRedirectionPolicyEnum }, optional: true, nullable: false
 
+        field :agent_id, -> { String }, optional: true, nullable: false
+
         field :oidc_support, -> { Auth0::Types::ClientOidcSupportPatch }, optional: true, nullable: false
       end
     end

data/lib/auth0/connections/keys/client.rb

@@ -11,7 +11,7 @@ module Auth0
           @client = client
         end
 
-        # Gets the connection keys for the Okta or OIDC connection strategy.
+        # Gets the connection keys for the Okta, OIDC, or SAML (samlp) connection strategy.
         #
         # @param request_options [Hash]
         # @param params [Hash]
@@ -48,9 +48,9 @@ module Auth0
           end
         end
 
-        # Provision initial connection keys for Okta or OIDC connection strategies. This endpoint allows you to create
-        # keys before configuring the connection to use Private Key JWT authentication, enabling zero-downtime
-        # transitions.
+        # Provision initial connection keys for Okta, OIDC, or SAML (samlp) connection strategies. This endpoint allows
+        # you to create keys before configuring the connection to use Private Key JWT authentication, enabling
+        # zero-downtime transitions.
         #
         # @param request_options [Hash]
         # @param params [Hash]
@@ -94,7 +94,7 @@ module Auth0
           end
         end
 
-        # Rotates the connection keys for the Okta or OIDC connection strategies.
+        # Rotates the connection keys for the Okta, OIDC, or SAML (samlp) connection strategies.
         #
         # @param request_options [Hash]
         # @param params [Hash]

data/lib/auth0/experimentation/experiments/client.rb

@@ -88,7 +88,8 @@ module Auth0
         #   client.experimentation.experiments.create(
         #     name: "name",
         #     feature_flag_id: "feature_flag_id",
-        #     authentication_flow: "authentication"
+        #     authentication_flow: "authentication",
+        #     allocation_strategy: "percentage"
         #   )
         #
         # @return [Auth0::Types::CreateExperimentResponseContent]

data/lib/auth0/experimentation/experiments/types/create_experiment_request_content.rb

@@ -15,7 +15,7 @@ module Auth0
 
           field :default_config, -> { Auth0::Types::DefaultConfigEnum }, optional: true, nullable: false
 
-          field :allocation_strategy, -> { Auth0::Types::AllocationStrategyEnum }, optional: true, nullable: false
+          field :allocation_strategy, -> { Auth0::Types::AllocationStrategyEnum }, optional: false, nullable: false
 
           field :allocations, -> { Internal::Types::Array[Auth0::Types::AllocationRequestItem] }, optional: true, nullable: false
 

data/lib/auth0/experimentation/segments/client.rb

@@ -23,12 +23,14 @@ module Auth0
         # @option params [String, nil] :from
         # @option params [Integer, nil] :take
         # @option params [Auth0::Types::SegmentTypeFilterEnum, nil] :type
+        # @option params [Auth0::Types::SegmentStatusEnum, nil] :status
         #
         # @example
         #   client.experimentation.segments.list(
         #     from: "from",
         #     take: 1,
-        #     type: "auth0"
+        #     type: "auth0",
+        #     status: "active"
         #   )
         #
         # @return [Auth0::Types::ListSegmentsResponseContent]
@@ -38,6 +40,7 @@ module Auth0
           query_params["from"] = params[:from] if params.key?(:from)
           query_params["take"] = params.fetch(:take, 50)
           query_params["type"] = params[:type] if params.key?(:type)
+          query_params["status"] = params[:status] if params.key?(:status)
 
           Auth0::Internal::CursorItemIterator.new(
             cursor_field: :next_,

data/lib/auth0/experimentation/segments/types/list_segments_request_parameters.rb

@@ -10,6 +10,8 @@ module Auth0
           field :take, -> { Integer }, optional: true, nullable: false
 
           field :type, -> { Auth0::Types::SegmentTypeFilterEnum }, optional: true, nullable: false
+
+          field :status, -> { Auth0::Types::SegmentStatusEnum }, optional: true, nullable: false
         end
       end
     end

data/lib/auth0/internal/http/rate_limit.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Auth0
+  module Internal
+    module Http
+      # Rate limit information parsed from the `x-ratelimit-*` headers Auth0
+      # returns on API responses.
+      #
+      # @see https://auth0.com/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy
+      class RateLimit
+        # @return [Integer, nil] the maximum number of requests allowed in the current window
+        attr_reader :limit
+        # @return [Integer, nil] the number of requests remaining in the current window
+        attr_reader :remaining
+        # @return [Time, nil] the UTC time at which the current window resets
+        attr_reader :reset
+
+        # @param limit [Integer, nil]
+        # @param remaining [Integer, nil]
+        # @param reset [Time, nil]
+        def initialize(limit:, remaining:, reset:)
+          @limit = limit
+          @remaining = remaining
+          @reset = reset
+        end
+
+        # Build from an object that exposes headers via `#[]` using the HTTP
+        # header name (e.g. a `Net::HTTPResponse`, whose `#[]` is
+        # case-insensitive). Used by the Management API (RawClient) path.
+        #
+        # @param response [#[]] responds to `[]` with header access
+        # @return [Auth0::Internal::Http::RateLimit]
+        def self.from_http_response(response)
+          build(
+            response["x-ratelimit-limit"],
+            response["x-ratelimit-remaining"],
+            response["x-ratelimit-reset"]
+          )
+        end
+
+        # Build from a plain headers hash (e.g. RestClient's, whose keys are
+        # symbols like `:x_ratelimit_remaining`). Keys are matched
+        # case-insensitively and dash/underscore-agnostically. Used by the
+        # Authentication API (HTTPProxy) path.
+        #
+        # @param headers [Hash, nil]
+        # @return [Auth0::Internal::Http::RateLimit]
+        def self.from_headers(headers)
+          normalized = (headers || {}).each_with_object({}) do |(key, value), acc|
+            acc[key.to_s.downcase.tr("-", "_")] = value
+          end
+
+          build(
+            normalized["x_ratelimit_limit"],
+            normalized["x_ratelimit_remaining"],
+            normalized["x_ratelimit_reset"]
+          )
+        end
+
+        # Invokes the handler with the given rate limit. A handler error must
+        # never break the caller's request, so it is rescued and warned rather
+        # than raised. Parsing happens before this call, so a parsing bug is not
+        # misattributed to the handler.
+        #
+        # @param handler [#call, nil] the configured rate limit handler
+        # @param rate_limit [Auth0::Internal::Http::RateLimit]
+        # @return [void]
+        def self.deliver(handler, rate_limit)
+          return if handler.nil?
+
+          handler.call(rate_limit)
+        rescue StandardError => e
+          warn "[auth0] rate_limit_handler raised #{e.class}: #{e.message}"
+        end
+
+        # @param limit [String, nil] raw `x-ratelimit-limit` value
+        # @param remaining [String, nil] raw `x-ratelimit-remaining` value
+        # @param reset [String, nil] raw `x-ratelimit-reset` value
+        # @return [Auth0::Internal::Http::RateLimit]
+        def self.build(limit, remaining, reset)
+          reset_epoch = to_integer(reset)
+
+          new(
+            limit: to_integer(limit),
+            remaining: to_integer(remaining),
+            reset: reset_epoch.nil? ? nil : Time.at(reset_epoch).utc
+          )
+        end
+        private_class_method :build
+
+        # Parse an integer header value, returning nil for blank or non-numeric
+        # input (so a malformed header is never silently reported as 0).
+        #
+        # @param value [String, nil] the raw header value
+        # @return [Integer, nil]
+        def self.to_integer(value)
+          Integer(value.to_s.strip, exception: false)
+        end
+        private_class_method :to_integer
+      end
+    end
+  end
+end

data/lib/auth0/internal/http/raw_client.rb

@@ -3,6 +3,8 @@
 # This file was auto-generated by Fern from our API Definition.
 # Modified by Auth0 to use Auth0 telemetry format with dynamic versioning.
 
+require_relative "rate_limit"
+
 module Auth0
   module Internal
     module Http
@@ -20,14 +22,21 @@ module Auth0
         # @return [String] The base URL for requests
         attr_reader :base_url
 
+        # @return [#call, nil] Optional callback invoked with an
+        #   {Auth0::Internal::Http::RateLimit} after every response.
+        attr_accessor :rate_limit_handler
+
         # @param base_url [String] The base url for the request.
         # @param max_retries [Integer] The number of times to retry a failed request, defaults to 2.
         # @param timeout [Float] The timeout for the request, defaults to 60.0 seconds.
         # @param headers [Hash] The headers for the request.
-        def initialize(base_url:, max_retries: 2, timeout: 60.0, headers: {})
+        # @param rate_limit_handler [#call, nil] Optional callback invoked with the
+        #   parsed rate limit (from the `x-ratelimit-*` headers) after every response.
+        def initialize(base_url:, max_retries: 2, timeout: 60.0, headers: {}, rate_limit_handler: nil)
           @base_url = base_url
           @max_retries = max_retries
           @timeout = timeout
+          @rate_limit_handler = rate_limit_handler
 
           # Auth0 telemetry in standard format
           telemetry = {
@@ -45,7 +54,7 @@ module Auth0
         end
 
         # @param request [Auth0::Internal::Http::BaseRequest] The HTTP request.
-        # @return [HTTP::Response] The HTTP response.
+        # @return [Net::HTTPResponse] The HTTP response.
         def send(request)
           url = build_url(request)
           attempt = 0
@@ -67,6 +76,9 @@ module Auth0
 
             response = conn.request(http_request)
 
+            # Report rate limit on every response, including retried 429s.
+            RateLimit.deliver(@rate_limit_handler, RateLimit.from_http_response(response)) if @rate_limit_handler
+
             break unless should_retry?(response, attempt)
 
             delay = retry_delay(response, attempt)

data/lib/auth0/mixins/httpproxy.rb

@@ -1,13 +1,14 @@
 require "addressable/uri"
 require "retryable"
 require_relative "../exception.rb"
+require_relative "../internal/http/rate_limit"
 
 module Auth0
   module Mixins
     # here's the proxy for Rest calls based on rest-client, we're building all request on that gem
     # for now, if you want to feel free to use your own http client
     module HTTPProxy
-      attr_accessor :headers, :base_uri, :timeout, :retry_count
+      attr_accessor :headers, :base_uri, :timeout, :retry_count, :rate_limit_handler
       DEFAULT_RETRIES = 3
       MAX_ALLOWED_RETRIES = 10
       MAX_REQUEST_RETRY_JITTER = 250
@@ -95,6 +96,13 @@ module Auth0
           call(method, encode_uri(uri), timeout, headers, body.to_json)
         end
 
+        # Surface rate limit for each response, including 429 retries. `call`
+        # returns nil for some errors (e.g. a dropped connection), so skip it then.
+        if @rate_limit_handler && !result.nil?
+          rate_limit = Auth0::Internal::Http::RateLimit.from_headers(result.headers)
+          Auth0::Internal::Http::RateLimit.deliver(@rate_limit_handler, rate_limit)
+        end
+
         case result.code
         when 200...226 then safe_parse_json(result.body)
         when 400       then raise Auth0::BadRequest.new(result.body, code: result.code, headers: result.headers)

data/lib/auth0/mixins/initializer.rb

@@ -21,6 +21,11 @@ module Auth0
         @management_timeout = options[:management_timeout]
         @management_max_retries = options[:management_max_retries]
         @management_additional_headers = options[:management_additional_headers]
+        handler = options[:rate_limit_handler]
+        raise ArgumentError, "rate_limit_handler must respond to #call" if handler && !handler.respond_to?(:call)
+
+        @rate_limit_handler = handler
+
         extend Auth0::Api::AuthenticationEndpoints
 
         @client_id = options[:client_id]