dodopayments 2.35.0 → 2.36.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 759472ef7ceda29e93921ba3842b3d7f64e23700c06195f12636ac0758c38ea2
-  data.tar.gz: 966be0a02c69b7f86643da56082d9a478199a658b2865a591b62684dbe294170
+  metadata.gz: 92bc6483e15b2acb4336b40dc7b0506cfcf6459c1df9534b5f2298f5c914578f
+  data.tar.gz: 031e012d15a53b9e54b167ecd3c294c82eec15c36f6553791b9831e53cdb5355
 SHA512:
-  metadata.gz: 9ee34c03c5070b13a2631a9a85d1e21477206be0f943dba2f08b6138949891e6eb68bec0778bb1adc4df471e6c1c89963c158c29606cd166263c66fe7b2830c5
-  data.tar.gz: b64bd1a280eb380543f5ec863b6034f4960b3fe886e1a684b4dd3324ef313b8ca3daca25a4da406ba654c2b44397539d690da6fcc424fb2f847bdb3a06d483dc
+  metadata.gz: 9a58eba2a64ac73d40c74e345aca8a06e15ecea1bbaa9e64e4812431ade3778748fe4fcdf543bba82fe8031fba96f9b25ab3cfd7059fc375dd27de5d348a28a5
+  data.tar.gz: 365c61a379aab7d5500c558a76d7153dda3486a4fabdd4af7e90185752aeeb18f2fa45f38116e714e58d5394315decff720996ed7c8ff31c6c111e6e9b35510a

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## [2.36.0](https://github.com/dodopayments/dodopayments-ruby/compare/v2.35.0...v2.36.0) (2026-10-28)
+
+
+### Features
+
+* **api:** regenerate SDK from latest OpenAPI spec ([8f4451c](https://github.com/dodopayments/dodopayments-ruby/commit/8f4451cf4bee3e5ed70f7d83b0e59ca1ca822a1e))
+* **api:** regenerate SDK from latest OpenAPI spec ([3089c6d](https://github.com/dodopayments/dodopayments-ruby/commit/3089c6df767756323fc412e46b4c78100727dd0b))
+* **api:** regenerate SDK from latest OpenAPI spec ([075d355](https://github.com/dodopayments/dodopayments-ruby/commit/075d35555b354afd7d6b3a4d16d1924805c28b4a))
+
 ## [2.35.0](https://github.com/dodopayments/dodopayments-ruby/compare/v2.34.0...v2.35.0) (2026-10-24)
 
 

data/README.md

@@ -23,7 +23,7 @@ To use this gem, install via Bundler by adding the following to your application
 <!-- x-release-please-start-version -->
 
 ```ruby
-gem "dodopayments", "~> 2.35.0"
+gem "dodopayments", "~> 2.36.0"
 ```
 
 <!-- x-release-please-end -->
@@ -72,6 +72,26 @@ if page.next_page?
 end
 ```
 
+### Workload identity
+
+Instead of an API key, the client can exchange an OIDC token (JWT) from your platform for a short-lived access token. The client caches the access token and gets a new one when 5 minutes or less remain.
+
+```ruby
+dodo_payments = Dodopayments::Client.new(
+  workload_identity: Dodopayments::WorkloadIdentity::Config.new(
+    identity_provider_id: "wip_...", # defaults to ENV["DODO_PAYMENTS_IDENTITY_PROVIDER_ID"]
+    provider: Dodopayments::WorkloadIdentity.github_actions
+  )
+)
+
+# Revoke the cached access token, for example at the end of a job.
+dodo_payments.workload_identity.revoke
+```
+
+The `Dodopayments::WorkloadIdentity` module has these token sources: `github_actions`, `gitlab`, `terraform_cloud`, `gcp`, `vercel`, `kubernetes`, `file`, `aws` (wraps your function), `static`, and `auto`. A `provider` can also be any object that responds to `call` and returns the JWT.
+
+Do not set `bearer_token` together with `workload_identity`. If you set neither, and `ENV["DODO_PAYMENTS_API_KEY"]` is not set, the client reads `ENV["DODO_PAYMENTS_IDENTITY_PROVIDER_ID"]` and uses the token source that `auto` finds.
+
 ### Handling errors
 
 When the library is unable to connect to the API, or if the API returns a non-success status code (i.e., 4xx or 5xx response), a subclass of `Dodopayments::Errors::APIError` will be thrown:

data/lib/dodopayments/client.rb

@@ -21,12 +21,17 @@ module Dodopayments
     # rubocop:enable Style/MutableConstant
 
     # Bearer Token for API authentication
-    # @return [String]
+    # @return [String, nil]
     attr_reader :bearer_token
 
     # @return [String, nil]
     attr_reader :webhook_key
 
+    # Workload identity session, or `nil` if the client uses a bearer token.
+    #
+    # @return [Dodopayments::WorkloadIdentity::Session, nil]
+    attr_reader :workload_identity
+
     # @return [Dodopayments::Resources::CheckoutSessions]
     attr_reader :checkout_sessions
 
@@ -114,12 +119,114 @@ module Dodopayments
       {"authorization" => "Bearer #{@bearer_token}"}
     end
 
+    # @api private
+    #
+    # With workload identity, a 401 response clears the cached access token. The
+    # client then gets a new access token and sends the request one more time.
+    #
+    # @param req [Hash{Symbol=>Object}]
+    #
+    # @raise [Dodopayments::Errors::APIError]
+    # @return [Object]
+    def request(req)
+      return super if @workload_identity.nil?
+
+      token = @workload_identity.access_token
+      begin
+        super(workload_identity_authorize(req, token))
+      rescue Dodopayments::Errors::AuthenticationError
+        @workload_identity.invalidate(token)
+        super(workload_identity_authorize(req, @workload_identity.access_token))
+      end
+    end
+
+    # @api private
+    #
+    # @param req [Hash{Symbol=>Object}]
+    # @param token [String]
+    #
+    # @return [Hash{Symbol=>Object}]
+    private def workload_identity_authorize(req, token)
+      {**req, headers: {**req[:headers].to_h, "authorization" => "Bearer #{token}"}}
+    end
+
+    # @api private
+    #
+    # Sends a workload identity request without the client credentials. It retries
+    # connection errors and 5xx responses, but not 4xx responses.
+    #
+    # @param method [Symbol]
+    # @param path [String]
+    # @param headers [Hash{String=>String}]
+    # @param body [Object, nil]
+    #
+    # @raise [Dodopayments::Errors::APIError]
+    # @return [Object]
+    private def workload_identity_request(method:, path:, headers:, body:)
+      url = Dodopayments::Internal::Util.join_parsed_uri(@base_url_components, {path: path})
+      headers = Dodopayments::Internal::Util.normalized_headers(@headers.except("authorization"), headers)
+      encoded = nil
+      if body.nil?
+        headers.delete("content-type")
+      else
+        headers, encoded = Dodopayments::Internal::Util.encode_content(headers, body)
+      end
+      request = {method: method, url: url, headers: headers, body: encoded, max_retries: 0, timeout: @timeout}
+
+      retry_count = 0
+      begin
+        _, response, stream = send_request(
+          request,
+          redirect_count: 0,
+          retry_count: retry_count,
+          send_retry_header: true
+        )
+      rescue Dodopayments::Errors::APIConnectionError, Dodopayments::Errors::InternalServerError => e
+        if retry_count < @max_retries
+          sleep(retry_delay(e.headers.to_h, retry_count: retry_count))
+          retry_count += 1
+          retry
+        end
+        raise workload_identity_error(e)
+      rescue Dodopayments::Errors::APIStatusError => e
+        raise workload_identity_error(e)
+      end
+
+      response_headers = Dodopayments::Internal::Util.normalized_headers(response.each_header.to_h)
+      Dodopayments::Internal::Util.decode_content(response_headers, stream: stream, suppress_error: true)
+    end
+
+    # @api private
+    #
+    # @param error [Dodopayments::Errors::APIError]
+    #
+    # @return [Dodopayments::Errors::APIError]
+    private def workload_identity_error(error)
+      return error unless error.is_a?(Dodopayments::Errors::APIStatusError)
+
+      body = error.body
+      details = body.is_a?(Hash) ? [body[:error], body[:error_description]].compact : []
+      message = ["Workload identity request failed with status #{error.status}", *details].join(": ")
+      Dodopayments::Errors::APIStatusError.for(
+        url: error.url,
+        status: error.status.to_i,
+        headers: error.headers,
+        body: body,
+        request: nil,
+        response: nil,
+        message: message
+      )
+    end
+
     # Creates and returns a new client for interacting with the API.
     #
     # @param bearer_token [String, nil] Bearer Token for API authentication Defaults to `ENV["DODO_PAYMENTS_API_KEY"]`
     #
     # @param webhook_key [String, nil] Defaults to `ENV["DODO_PAYMENTS_WEBHOOK_KEY"]`
     #
+    # @param workload_identity [Dodopayments::WorkloadIdentity::Config, Hash{Symbol=>Object}, nil] Exchange an OIDC token for an access token, instead of a bearer token. See
+    # {Dodopayments::WorkloadIdentity}.
+    #
     # @param environment [:live_mode, :test_mode, nil] Specifies the environment to use for the API.
     #
     # Each environment maps to a different base URL:
@@ -138,8 +245,9 @@ module Dodopayments
     #
     # @param max_retry_delay [Float]
     def initialize(
-      bearer_token: ENV["DODO_PAYMENTS_API_KEY"],
+      bearer_token: nil,
       webhook_key: ENV["DODO_PAYMENTS_WEBHOOK_KEY"],
+      workload_identity: nil,
       environment: nil,
       base_url: ENV["DODO_PAYMENTS_BASE_URL"],
       max_retries: self.class::DEFAULT_MAX_RETRIES,
@@ -152,7 +260,17 @@ module Dodopayments
         raise ArgumentError.new(message)
       end
 
-      if bearer_token.nil?
+      unless bearer_token.nil? || workload_identity.nil?
+        raise ArgumentError.new("bearer_token and workload_identity cannot be used together")
+      end
+      bearer_token = ENV["DODO_PAYMENTS_API_KEY"] if bearer_token.nil? && workload_identity.nil?
+      if bearer_token.nil? && workload_identity.nil? && !ENV["DODO_PAYMENTS_IDENTITY_PROVIDER_ID"].to_s.empty?
+        provider = Dodopayments::WorkloadIdentity.auto
+        workload_identity = {provider: provider} unless provider.nil?
+      end
+      workload_identity = Dodopayments::WorkloadIdentity::Config.coerce(workload_identity) unless workload_identity.nil?
+
+      if bearer_token.nil? && workload_identity.nil?
         raise ArgumentError.new("bearer_token is required, and can be set via environ: \"DODO_PAYMENTS_API_KEY\"")
       end
 
@@ -169,7 +287,7 @@ module Dodopayments
         headers = parsed.merge(headers)
       end
 
-      @bearer_token = bearer_token.to_s
+      @bearer_token = bearer_token&.to_s
       @webhook_key = webhook_key&.to_s
 
       super(
@@ -207,6 +325,17 @@ module Dodopayments
       @entitlements = Dodopayments::Resources::Entitlements.new(client: self)
       @product_collections = Dodopayments::Resources::ProductCollections.new(client: self)
       @moderation = Dodopayments::Resources::Moderation.new(client: self)
+
+      @workload_identity = nil
+      return if workload_identity.nil?
+      @workload_identity = Dodopayments::WorkloadIdentity::Session.new(
+        config: workload_identity,
+        context: Dodopayments::WorkloadIdentity::Context.new(
+          base_url: @base_url,
+          audience: Dodopayments::Internal::Util.uri_origin(@base_url)
+        ),
+        transport: method(:workload_identity_request)
+      )
     end
   end
 end

data/lib/dodopayments/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Dodopayments
-  VERSION = "2.35.0"
+  VERSION = "2.36.0"
 end

data/lib/dodopayments/workload_identity.rb

@@ -0,0 +1,351 @@
+# frozen_string_literal: true
+
+module Dodopayments
+  # Workload identity federation: exchange a short-lived OIDC token (JWT) from
+  # your platform for a short-lived API access token.
+  #
+  # @example
+  #   client = Dodopayments::Client.new(
+  #     workload_identity: Dodopayments::WorkloadIdentity::Config.new(
+  #       identity_provider_id: "wip_...",
+  #       provider: Dodopayments::WorkloadIdentity.github_actions
+  #     )
+  #   )
+  module WorkloadIdentity
+    # @api private
+    GRANT_TYPE = "urn:ietf:params:oauth:grant-type:token-exchange"
+
+    # @api private
+    SUBJECT_TOKEN_TYPE = "urn:ietf:params:oauth:token-type:jwt"
+
+    # The client refreshes the access token when this many seconds or less remain.
+    REFRESH_WINDOW_IN_SECONDS = 300
+
+    # @api private
+    PROVIDER_TIMEOUT_IN_SECONDS = 10
+
+    # @api private
+    KUBERNETES_TOKEN_PATH = "/var/run/secrets/tokens/dodo-token"
+
+    # @api private
+    GCP_METADATA_URL =
+      "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity"
+
+    # The values that a subject token provider gets on each token exchange.
+    class Context
+      # The base URL of the client.
+      # @return [URI::Generic]
+      attr_reader :base_url
+
+      # The default audience: the origin of the client base URL.
+      # @return [String]
+      attr_reader :audience
+
+      # @api private
+      #
+      # @param base_url [URI::Generic]
+      # @param audience [String]
+      def initialize(base_url:, audience:)
+        @base_url = base_url
+        @audience = audience
+      end
+    end
+
+    # The `workload_identity` option of {Dodopayments::Client}.
+    class Config
+      # @return [String]
+      attr_reader :identity_provider_id
+
+      # @return [#call]
+      attr_reader :provider
+
+      # @param provider [#call] Returns the subject token (a JWT string). It can take one
+      # argument, a {Dodopayments::WorkloadIdentity::Context}.
+      #
+      # @param identity_provider_id [String, nil] Defaults to `ENV["DODO_PAYMENTS_IDENTITY_PROVIDER_ID"]`
+      def initialize(provider:, identity_provider_id: ENV["DODO_PAYMENTS_IDENTITY_PROVIDER_ID"])
+        if identity_provider_id.nil? || identity_provider_id.to_s.empty?
+          raise ArgumentError.new(
+            "identity_provider_id is required, and can be set via environ: \"DODO_PAYMENTS_IDENTITY_PROVIDER_ID\""
+          )
+        end
+        unless provider.respond_to?(:call)
+          raise ArgumentError.new("provider must respond to `call`")
+        end
+
+        @identity_provider_id = identity_provider_id.to_s
+        @provider = provider
+      end
+
+      # @api private
+      #
+      # @param value [Dodopayments::WorkloadIdentity::Config, Hash{Symbol=>Object}]
+      #
+      # @return [Dodopayments::WorkloadIdentity::Config]
+      def self.coerce(value)
+        case value
+        in Dodopayments::WorkloadIdentity::Config
+          value
+        in Hash
+          new(**value)
+        else
+          raise ArgumentError.new("workload_identity must be a #{name} or a Hash, got #{value.class}")
+        end
+      end
+
+      # @return [String]
+      def inspect = "#<#{self.class.name} identity_provider_id=#{@identity_provider_id}>"
+    end
+
+    # Caches the access token of one client. All methods are thread-safe.
+    class Session
+      # @return [String]
+      attr_reader :identity_provider_id
+
+      # @api private
+      #
+      # @param config [Dodopayments::WorkloadIdentity::Config]
+      # @param context [Dodopayments::WorkloadIdentity::Context]
+      # @param transport [Proc] Sends a request without the client credentials.
+      def initialize(config:, context:, transport:)
+        @identity_provider_id = config.identity_provider_id
+        @provider = config.provider
+        @context = context
+        @transport = transport
+        @mutex = Mutex.new
+        @access_token = nil
+        @expires_at = nil
+      end
+
+      # Returns a valid access token. This method does a token exchange if no token is
+      # cached, or if 5 minutes or less remain. Concurrent callers share one exchange.
+      #
+      # @raise [Dodopayments::Errors::APIError]
+      # @return [String]
+      def access_token
+        @mutex.synchronize do
+          exchange! unless fresh?
+          @access_token.to_s
+        end
+      end
+
+      # @api private
+      #
+      # Clears the cache, but only if it still holds `token`.
+      #
+      # @param token [String, nil]
+      def invalidate(token = nil)
+        @mutex.synchronize do
+          clear! if token.nil? || token == @access_token
+        end
+        nil
+      end
+
+      # Revokes the cached access token and clears the cache. Does nothing if no token
+      # is cached.
+      #
+      # @raise [Dodopayments::Errors::APIError]
+      def revoke
+        token = @mutex.synchronize { @access_token }
+        return if token.nil?
+
+        begin
+          @transport.call(
+            method: :post,
+            path: "workload-identity/token/revoke",
+            headers: {"authorization" => "Bearer #{token}"},
+            body: nil
+          )
+        ensure
+          invalidate(token)
+        end
+        nil
+      end
+
+      # @return [String]
+      def inspect = "#<#{self.class.name} identity_provider_id=#{@identity_provider_id}>"
+
+      private def fresh?
+        !@access_token.nil? && !@expires_at.nil? && @expires_at - Time.now > REFRESH_WINDOW_IN_SECONDS
+      end
+
+      private def clear!
+        @access_token = nil
+        @expires_at = nil
+      end
+
+      private def subject_token
+        token = @provider.respond_to?(:arity) && @provider.arity.zero? ? @provider.call : @provider.call(@context)
+        if !token.is_a?(String) || token.strip.empty?
+          raise Dodopayments::Errors::Error.new("The workload identity provider did not return a token")
+        end
+        token.strip
+      end
+
+      private def exchange!
+        clear!
+        body = {
+          grant_type: GRANT_TYPE,
+          subject_token_type: SUBJECT_TOKEN_TYPE,
+          subject_token: subject_token,
+          identity_provider_id: @identity_provider_id
+        }
+        now = Time.now
+        response = @transport.call(method: :post, path: "workload-identity/token", headers: {}, body: body)
+        token = response.is_a?(Hash) ? response[:access_token] : nil
+        if !token.is_a?(String) || token.empty?
+          raise Dodopayments::Errors::Error.new("The token exchange response has no access_token")
+        end
+
+        @expires_at = expiry(response, now: now)
+        @access_token = token
+      end
+
+      private def expiry(response, now:)
+        expires_at = response[:expires_at]
+        if expires_at.is_a?(String)
+          begin
+            return Time.iso8601(expires_at)
+          rescue ArgumentError
+            nil
+          end
+        end
+        now + Float(response[:expires_in], exception: false).to_f
+      end
+    end
+
+    class << self
+      # GitHub Actions. The job must have the `id-token: write` permission.
+      #
+      # @param audience [String, nil] Defaults to the origin of the client base URL.
+      #
+      # @return [Proc]
+      def github_actions(audience: nil)
+        lambda do |context|
+          url = env!("ACTIONS_ID_TOKEN_REQUEST_URL")
+          request_token = env!("ACTIONS_ID_TOKEN_REQUEST_TOKEN")
+          separator = url.include?("?") ? "&" : "?"
+          uri = URI("#{url}#{separator}audience=#{CGI.escape(audience || context.audience)}")
+          body = http_get(uri, {"authorization" => "bearer #{request_token}"})
+          JSON.parse(body).fetch("value")
+        end
+      end
+
+      # GitLab CI/CD. Declare the token in `id_tokens` of the job.
+      #
+      # @param env_var [String]
+      #
+      # @return [Proc]
+      def gitlab(env_var: "DODO_PAYMENTS_ID_TOKEN") = ->(_context = nil) { env!(env_var) }
+
+      # HCP Terraform (Terraform Cloud) dynamic credentials.
+      #
+      # @return [Proc]
+      def terraform_cloud
+        lambda do |_context = nil|
+          ENV["TFC_WORKLOAD_IDENTITY_TOKEN"] || env!("TFC_WORKLOAD_IDENTITY_TOKEN_DODO")
+        end
+      end
+
+      # Google Cloud: the metadata server of the attached service account.
+      #
+      # @param audience [String, nil] Defaults to the origin of the client base URL.
+      #
+      # @return [Proc]
+      def gcp(audience: nil)
+        lambda do |context|
+          query = URI.encode_www_form(audience: audience || context.audience, format: "full")
+          http_get(URI("#{GCP_METADATA_URL}?#{query}"), {"metadata-flavor" => "Google"})
+        end
+      end
+
+      # Vercel OIDC federation.
+      #
+      # @return [Proc]
+      def vercel = ->(_context = nil) { env!("VERCEL_OIDC_TOKEN") }
+
+      # Kubernetes: a projected service account token. The file is read on each exchange.
+      #
+      # @param path [String]
+      #
+      # @return [Proc]
+      def kubernetes(path: KUBERNETES_TOKEN_PATH) = file(path: path)
+
+      # A token file. The file is read on each exchange.
+      #
+      # @param path [String, nil] Defaults to `ENV["DODO_PAYMENTS_IDENTITY_TOKEN_FILE"]`
+      #
+      # @return [Proc]
+      def file(path: ENV["DODO_PAYMENTS_IDENTITY_TOKEN_FILE"])
+        if path.nil? || path.empty?
+          raise ArgumentError.new(
+            "path is required, and can be set via environ: \"DODO_PAYMENTS_IDENTITY_TOKEN_FILE\""
+          )
+        end
+        ->(_context = nil) { File.read(path).strip }
+      end
+
+      # AWS: wraps your function that returns the JWT, for example from STS
+      # `GetWebIdentityToken`.
+      #
+      # @param fn [#call, nil]
+      #
+      # @return [Proc]
+      def aws(fn = nil, &blk)
+        callable = fn || blk
+        raise ArgumentError.new("aws requires a function or a block") if callable.nil?
+        ->(_context = nil) { callable.call }
+      end
+
+      # A fixed token. Use it for tests.
+      #
+      # @param token [String]
+      #
+      # @return [Proc]
+      def static(token) = ->(_context = nil) { token }
+
+      # Finds a token source in the environment, in this order: GitHub Actions, HCP
+      # Terraform, `ENV["DODO_PAYMENTS_IDENTITY_TOKEN_FILE"]`, and the Kubernetes path.
+      #
+      # @return [Proc, nil] `nil` if no source is found.
+      def auto
+        if ENV["ACTIONS_ID_TOKEN_REQUEST_URL"] && ENV["ACTIONS_ID_TOKEN_REQUEST_TOKEN"]
+          return github_actions
+        end
+        if ENV["TFC_WORKLOAD_IDENTITY_TOKEN"] || ENV["TFC_WORKLOAD_IDENTITY_TOKEN_DODO"]
+          return terraform_cloud
+        end
+        path = ENV["DODO_PAYMENTS_IDENTITY_TOKEN_FILE"]
+        return file(path: path) unless path.nil? || path.empty?
+        return kubernetes if File.file?(KUBERNETES_TOKEN_PATH)
+        nil
+      end
+
+      private def env!(name)
+        value = ENV[name]
+        if value.nil? || value.empty?
+          raise Dodopayments::Errors::Error.new("The environment variable #{name} is not set")
+        end
+        value
+      end
+
+      private def http_get(uri, headers)
+        response = Net::HTTP.start(
+          uri.host,
+          uri.port,
+          use_ssl: uri.scheme == "https",
+          open_timeout: PROVIDER_TIMEOUT_IN_SECONDS,
+          read_timeout: PROVIDER_TIMEOUT_IN_SECONDS
+        ) do |http|
+          http.get(uri.request_uri, headers)
+        end
+        unless response.is_a?(Net::HTTPSuccess)
+          raise Dodopayments::Errors::Error.new(
+            "The subject token request to #{uri.host} failed with status #{response.code}"
+          )
+        end
+        response.body.to_s
+      end
+    end
+  end
+end

data/lib/dodopayments.rb

@@ -55,6 +55,7 @@ require_relative "dodopayments/internal/transport/pooled_net_requester"
 require_relative "dodopayments/client"
 require_relative "dodopayments/internal/cursor_page_pagination"
 require_relative "dodopayments/internal/default_page_number_pagination"
+require_relative "dodopayments/workload_identity"
 require_relative "dodopayments/models/blocklist/block_by_email"
 require_relative "dodopayments/models/blocklist/block_by_customer_id"
 require_relative "dodopayments/models/blocklist/create_blocked_customer_request"

data/rbi/dodopayments/client.rbi

@@ -20,12 +20,15 @@ module Dodopayments
       )
 
     # Bearer Token for API authentication
-    sig { returns(String) }
+    sig { returns(T.nilable(String)) }
     attr_reader :bearer_token
 
     sig { returns(T.nilable(String)) }
     attr_reader :webhook_key
 
+    sig { returns(T.nilable(Dodopayments::WorkloadIdentity::Session)) }
+    attr_reader :workload_identity
+
     sig { returns(Dodopayments::Resources::CheckoutSessions) }
     attr_reader :checkout_sessions
 
@@ -114,6 +117,13 @@ module Dodopayments
       params(
         bearer_token: T.nilable(String),
         webhook_key: T.nilable(String),
+        workload_identity:
+          T.nilable(
+            T.any(
+              Dodopayments::WorkloadIdentity::Config,
+              T::Hash[Symbol, T.anything]
+            )
+          ),
         environment: T.nilable(T.any(Symbol, String)),
         base_url: T.nilable(String),
         max_retries: Integer,
@@ -124,9 +134,12 @@ module Dodopayments
     end
     def self.new(
       # Bearer Token for API authentication Defaults to `ENV["DODO_PAYMENTS_API_KEY"]`
-      bearer_token: ENV["DODO_PAYMENTS_API_KEY"],
+      bearer_token: nil,
       # Defaults to `ENV["DODO_PAYMENTS_WEBHOOK_KEY"]`
       webhook_key: ENV["DODO_PAYMENTS_WEBHOOK_KEY"],
+      # Exchange an OIDC token for an access token, instead of a bearer token. See
+      # {Dodopayments::WorkloadIdentity}.
+      workload_identity: nil,
       # Specifies the environment to use for the API.
       #
       # Each environment maps to a different base URL:

data/rbi/dodopayments/workload_identity.rbi

@@ -0,0 +1,219 @@
+# typed: strong
+
+# typed: strong
+
+module Dodopayments
+  # Workload identity federation: exchange a short-lived OIDC token (JWT) from
+  # your platform for a short-lived API access token.
+  module WorkloadIdentity
+    GRANT_TYPE = T.let(T.unsafe(nil), String)
+
+    SUBJECT_TOKEN_TYPE = T.let(T.unsafe(nil), String)
+
+    # The client refreshes the access token when this many seconds or less remain.
+    REFRESH_WINDOW_IN_SECONDS = T.let(T.unsafe(nil), Integer)
+
+    PROVIDER_TIMEOUT_IN_SECONDS = T.let(T.unsafe(nil), Integer)
+
+    KUBERNETES_TOKEN_PATH = T.let(T.unsafe(nil), String)
+
+    GCP_METADATA_URL = T.let(T.unsafe(nil), String)
+
+    # The values that a subject token provider gets on each token exchange.
+    class Context
+      # The base URL of the client.
+      sig { returns(URI::Generic) }
+      attr_reader :base_url
+
+      # The default audience: the origin of the client base URL.
+      sig { returns(String) }
+      attr_reader :audience
+
+      # @api private
+      sig do
+        params(base_url: URI::Generic, audience: String).returns(
+          T.attached_class
+        )
+      end
+      def self.new(base_url:, audience:)
+      end
+    end
+
+    # The `workload_identity` option of the client.
+    class Config
+      sig { returns(String) }
+      attr_reader :identity_provider_id
+
+      sig { returns(T.anything) }
+      attr_reader :provider
+
+      sig do
+        params(
+          provider: T.anything,
+          identity_provider_id: T.nilable(String)
+        ).returns(T.attached_class)
+      end
+      def self.new(
+        # Returns the subject token (a JWT string). It can take one argument, a
+        # `WorkloadIdentity::Context`.
+        provider:,
+        # Defaults to `ENV["DODO_PAYMENTS_IDENTITY_PROVIDER_ID"]`
+        identity_provider_id: ENV["DODO_PAYMENTS_IDENTITY_PROVIDER_ID"]
+      )
+      end
+
+      # @api private
+      sig do
+        params(
+          value:
+            T.any(
+              Dodopayments::WorkloadIdentity::Config,
+              T::Hash[Symbol, T.anything]
+            )
+        ).returns(Dodopayments::WorkloadIdentity::Config)
+      end
+      def self.coerce(value)
+      end
+
+      sig { returns(String) }
+      def inspect
+      end
+    end
+
+    # Caches the access token of one client. All methods are thread-safe.
+    class Session
+      sig { returns(String) }
+      attr_reader :identity_provider_id
+
+      # @api private
+      sig do
+        params(
+          config: Dodopayments::WorkloadIdentity::Config,
+          context: Dodopayments::WorkloadIdentity::Context,
+          transport: T.anything
+        ).returns(T.attached_class)
+      end
+      def self.new(config:, context:, transport:)
+      end
+
+      # Returns a valid access token. This method does a token exchange if no token is
+      # cached, or if 5 minutes or less remain. Concurrent callers share one exchange.
+      sig { returns(String) }
+      def access_token
+      end
+
+      # @api private
+      sig { params(token: T.nilable(String)).returns(NilClass) }
+      def invalidate(token = nil)
+      end
+
+      # Revokes the cached access token and clears the cache. Does nothing if no token
+      # is cached.
+      sig { returns(NilClass) }
+      def revoke
+      end
+
+      sig { returns(String) }
+      def inspect
+      end
+    end
+
+    Provider =
+      T.type_alias do
+        T
+          .proc
+          .params(context: Dodopayments::WorkloadIdentity::Context)
+          .returns(String)
+      end
+
+    class << self
+      # GitHub Actions. The job must have the `id-token: write` permission.
+      sig do
+        params(audience: T.nilable(String)).returns(
+          Dodopayments::WorkloadIdentity::Provider
+        )
+      end
+      def github_actions(
+        # Defaults to the origin of the client base URL.
+        audience: nil
+      )
+      end
+
+      # GitLab CI/CD. Declare the token in `id_tokens` of the job.
+      sig do
+        params(env_var: String).returns(
+          Dodopayments::WorkloadIdentity::Provider
+        )
+      end
+      def gitlab(env_var: "DODO_PAYMENTS_ID_TOKEN")
+      end
+
+      # HCP Terraform (Terraform Cloud) dynamic credentials.
+      sig { returns(Dodopayments::WorkloadIdentity::Provider) }
+      def terraform_cloud
+      end
+
+      # Google Cloud: the metadata server of the attached service account.
+      sig do
+        params(audience: T.nilable(String)).returns(
+          Dodopayments::WorkloadIdentity::Provider
+        )
+      end
+      def gcp(
+        # Defaults to the origin of the client base URL.
+        audience: nil
+      )
+      end
+
+      # Vercel OIDC federation.
+      sig { returns(Dodopayments::WorkloadIdentity::Provider) }
+      def vercel
+      end
+
+      # Kubernetes: a projected service account token. The file is read on each
+      # exchange.
+      sig do
+        params(path: String).returns(Dodopayments::WorkloadIdentity::Provider)
+      end
+      def kubernetes(path: KUBERNETES_TOKEN_PATH)
+      end
+
+      # A token file. The file is read on each exchange.
+      sig do
+        params(path: T.nilable(String)).returns(
+          Dodopayments::WorkloadIdentity::Provider
+        )
+      end
+      def file(
+        # Defaults to `ENV["DODO_PAYMENTS_IDENTITY_TOKEN_FILE"]`
+        path: ENV["DODO_PAYMENTS_IDENTITY_TOKEN_FILE"]
+      )
+      end
+
+      # AWS: wraps your function that returns the JWT, for example from STS
+      # `GetWebIdentityToken`.
+      sig do
+        params(
+          fn: T.nilable(T.anything),
+          blk: T.nilable(T.proc.returns(String))
+        ).returns(Dodopayments::WorkloadIdentity::Provider)
+      end
+      def aws(fn = nil, &blk)
+      end
+
+      # A fixed token. Use it for tests.
+      sig do
+        params(token: String).returns(Dodopayments::WorkloadIdentity::Provider)
+      end
+      def static(token)
+      end
+
+      # Finds a token source in the environment, in this order: GitHub Actions, HCP
+      # Terraform, `ENV["DODO_PAYMENTS_IDENTITY_TOKEN_FILE"]`, and the Kubernetes path.
+      # Returns `nil` if no source is found.
+      sig { returns(T.nilable(Dodopayments::WorkloadIdentity::Provider)) }
+      def auto
+      end
+    end
+  end
+end

data/sig/dodopayments/client.rbs

@@ -13,10 +13,12 @@ module Dodopayments
       test_mode: "https://test.dodopayments.com"
     }
 
-    attr_reader bearer_token: String
+    attr_reader bearer_token: String?
 
     attr_reader webhook_key: String?
 
+    attr_reader workload_identity: Dodopayments::WorkloadIdentity::Session?
+
     attr_reader checkout_sessions: Dodopayments::Resources::CheckoutSessions
 
     attr_reader payments: Dodopayments::Resources::Payments
@@ -74,6 +76,9 @@ module Dodopayments
     def initialize: (
       ?bearer_token: String?,
       ?webhook_key: String?,
+      ?workload_identity: Dodopayments::WorkloadIdentity::Config
+      | ::Hash[Symbol, top]
+      | nil,
       ?environment: :live_mode | :test_mode | nil,
       ?base_url: String?,
       ?max_retries: Integer,

data/sig/dodopayments/workload_identity.rbs

@@ -0,0 +1,89 @@
+module Dodopayments
+  module WorkloadIdentity
+    GRANT_TYPE: String
+
+    SUBJECT_TOKEN_TYPE: String
+
+    REFRESH_WINDOW_IN_SECONDS: Integer
+
+    PROVIDER_TIMEOUT_IN_SECONDS: Integer
+
+    KUBERNETES_TOKEN_PATH: String
+
+    GCP_METADATA_URL: String
+
+    type provider = ^(Dodopayments::WorkloadIdentity::Context context) -> String
+
+    class Context
+      attr_reader base_url: URI::Generic
+
+      attr_reader audience: String
+
+      def initialize: (base_url: URI::Generic, audience: String) -> void
+    end
+
+    class Config
+      attr_reader identity_provider_id: String
+
+      attr_reader provider: top
+
+      def initialize: (provider: top, ?identity_provider_id: String?) -> void
+
+      def self.coerce: (
+        Dodopayments::WorkloadIdentity::Config | ::Hash[Symbol, top] value
+      ) -> Dodopayments::WorkloadIdentity::Config
+
+      def inspect: -> String
+    end
+
+    class Session
+      attr_reader identity_provider_id: String
+
+      def initialize: (
+        config: Dodopayments::WorkloadIdentity::Config,
+        context: Dodopayments::WorkloadIdentity::Context,
+        transport: top
+      ) -> void
+
+      def access_token: -> String
+
+      def invalidate: (?String? token) -> nil
+
+      def revoke: -> nil
+
+      def inspect: -> String
+    end
+
+    def self.github_actions: (
+      ?audience: String?
+    ) -> Dodopayments::WorkloadIdentity::provider
+
+    def self.gitlab: (
+      ?env_var: String
+    ) -> Dodopayments::WorkloadIdentity::provider
+
+    def self.terraform_cloud: -> Dodopayments::WorkloadIdentity::provider
+
+    def self.gcp: (
+      ?audience: String?
+    ) -> Dodopayments::WorkloadIdentity::provider
+
+    def self.vercel: -> Dodopayments::WorkloadIdentity::provider
+
+    def self.kubernetes: (
+      ?path: String
+    ) -> Dodopayments::WorkloadIdentity::provider
+
+    def self.file: (?path: String?) -> Dodopayments::WorkloadIdentity::provider
+
+    def self.aws: (
+      ?top fn
+    ) ?{
+      -> String
+    } -> Dodopayments::WorkloadIdentity::provider
+
+    def self.static: (String token) -> Dodopayments::WorkloadIdentity::provider
+
+    def self.auto: -> Dodopayments::WorkloadIdentity::provider?
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: dodopayments
 version: !ruby/object:Gem::Version
-  version: 2.35.0
+  version: 2.36.0
 platform: ruby
 authors:
 - Dodo Payments
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-24 00:00:00.000000000 Z
+date: 2026-10-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: cgi
@@ -542,6 +542,7 @@ files:
 - lib/dodopayments/resources/webhooks.rb
 - lib/dodopayments/resources/webhooks/headers.rb
 - lib/dodopayments/version.rb
+- lib/dodopayments/workload_identity.rb
 - manifest.yaml
 - rbi/dodopayments/client.rbi
 - rbi/dodopayments/errors.rbi
@@ -1021,6 +1022,7 @@ files:
 - rbi/dodopayments/resources/webhooks.rbi
 - rbi/dodopayments/resources/webhooks/headers.rbi
 - rbi/dodopayments/version.rbi
+- rbi/dodopayments/workload_identity.rbi
 - sig/dodopayments/client.rbs
 - sig/dodopayments/errors.rbs
 - sig/dodopayments/file_part.rbs
@@ -1499,6 +1501,7 @@ files:
 - sig/dodopayments/resources/webhooks.rbs
 - sig/dodopayments/resources/webhooks/headers.rbs
 - sig/dodopayments/version.rbs
+- sig/dodopayments/workload_identity.rbs
 homepage: https://gemdocs.org/gems/dodopayments
 licenses: []
 metadata: