openai 0.57.0 → 0.58.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1b3abca0a4ee2539ad853331fb8ba61b722546103cd80ab21e983af50b12b53b
-  data.tar.gz: 303c04c16a7dd957587657d7adc826a6baa096b0805609c35f6b56d7fd3c03c1
+  metadata.gz: 73c6650d695d8ce23e2049359d56d6d4d2ae68971afb993c362f09b2f7bcfa37
+  data.tar.gz: 7a47b51f536ab52ce437c98663f56642d67638a187cba7055be29b79185630a0
 SHA512:
-  metadata.gz: 2150df450775d2f132f901d485aaf115831036dfecc438ca1eed13d89d44fc01eabde37c559dd1c834e490bee861ac43358a0237a93247586c3d08e77a960c0c
-  data.tar.gz: b3c47548b3b6ef867128331819dcada070087ba3028beaa1b7578a67ec1de7b7309aec8fafcadf1643717f70fc4799236999e74041c1eccd9dc341a80b7aca9e
+  metadata.gz: 84bf4110e464bab432883383984801d45c6cc9dc9dc40d23a8b70c1ceda3c498d7a835fb55773f9734e7f0891bf763d2fb71d213539b04993027518b158eb9ce
+  data.tar.gz: fa6a7d0c969bb6a6b70779e827cb5756e8420c21b986a313bd7d8e7d00663f6f300f75d61a51156831080f6510579a79523e2433189c356d63d9ba739f9021b7

data/CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## 0.58.0 (2026-04-08)
+
+Full Changelog: [v0.57.0...v0.58.0](https://github.com/openai/openai-ruby/compare/v0.57.0...v0.58.0)
+
+### Features
+
+* **api:** add phase field to conversations message model ([a5dc6f8](https://github.com/openai/openai-ruby/commit/a5dc6f85304b7271da53b91e581cc7c124e5a3b0))
+* **api:** add WEB_SEARCH_CALL_RESULTS to ResponseIncludable enum ([a556507](https://github.com/openai/openai-ruby/commit/a55650709792c28327253e054a849ed293167fc9))
+* **client:** add support for short-lived tokens ([#1311](https://github.com/openai/openai-ruby/issues/1311)) ([a86d3bc](https://github.com/openai/openai-ruby/commit/a86d3bccd6cfe6b003d7383a525b7285ddd4b4b5))
+
+
+### Bug Fixes
+
+* align path encoding with RFC 3986 section 3.3 ([8058a6d](https://github.com/openai/openai-ruby/commit/8058a6d56f8ad87bf6cd840760eff58f1b9fd973))
+* **api:** remove web_search_call.results from ResponseIncludable enum ([2861387](https://github.com/openai/openai-ruby/commit/2861387a6f43db7d7e7cc703022b0093b27723b9))
+* **internal:** correct multipart form field name encoding ([683d14b](https://github.com/openai/openai-ruby/commit/683d14b37f2b57d5273fbb5ed1e5c6d2aea20f4d))
+* multipart encoding for file arrays ([755b444](https://github.com/openai/openai-ruby/commit/755b4448c4065a2bc2993f718e1ced82b99b6ebf))
+* variable name typo ([6b333a4](https://github.com/openai/openai-ruby/commit/6b333a4c4a76ad8cc91f6696ca8352c633381cfc))
+
+
+### Chores
+
+* **ci:** support opting out of skipping builds on metadata-only commits ([1b6ddfa](https://github.com/openai/openai-ruby/commit/1b6ddfa633228b299115e84918be246ec60e95d8))
+* **tests:** bump steady to v0.20.1 ([952ea68](https://github.com/openai/openai-ruby/commit/952ea68c40059c7dbaacc1f2238e04d7191b31d9))
+* **tests:** bump steady to v0.20.2 ([615427b](https://github.com/openai/openai-ruby/commit/615427b02e022b32824303b303a1cf1a5d528a58))
+
+
+### Documentation
+
+* **api:** update file parameter descriptions in vector_stores ([260e754](https://github.com/openai/openai-ruby/commit/260e754f501203b1a4e7c17a2ace1642b5194d52))
+
 ## 0.57.0 (2026-03-25)
 
 Full Changelog: [v0.56.0...v0.57.0](https://github.com/openai/openai-ruby/compare/v0.56.0...v0.57.0)

data/README.md

@@ -15,7 +15,7 @@ To use this gem, install via Bundler by adding the following to your application
 <!-- x-release-please-start-version -->
 
 ```ruby
-gem "openai", "~> 0.57.0"
+gem "openai", "~> 0.58.0"
 ```
 
 <!-- x-release-please-end -->
@@ -107,6 +107,103 @@ puts(edited.data.first)
 
 Note that you can also pass a raw `IO` descriptor, but this disables retries, as the library can't be sure if the descriptor is a file or pipe (which cannot be rewound).
 
+## Workload Identity Authentication
+
+For secure, automated environments like cloud-managed Kubernetes, Azure, and GCP, you can use workload identity authentication with short-lived tokens from cloud identity providers instead of long-lived API keys.
+
+
+### Kubernetes Service Account
+
+```ruby
+require "openai"
+
+# Configure Kubernetes service account provider
+provider = OpenAI::Auth::SubjectTokenProviders::K8sServiceAccountTokenProvider.new
+
+workload_identity = OpenAI::Auth::WorkloadIdentity.new(
+  client_id: ENV["OAUTH_CLIENT_ID"], # This is the default and can be omitted
+  identity_provider_id: ENV["IDENTITY_PROVIDER_ID"], # This is the default and can be omitted
+  service_account_id: ENV["SERVICE_ACCOUNT_ID"], # This is the default and can be omitted
+  provider: provider
+)
+
+client = OpenAI::Client.new(
+  workload_identity: workload_identity,
+)
+
+response = client.chat.completions.create(
+  messages: [{role: "user", content: "Hello!"}],
+  model: "gpt-5.2"
+)
+```
+
+### Azure Managed Identity
+
+```ruby
+provider = OpenAI::Auth::SubjectTokenProviders::AzureManagedIdentityTokenProvider.new
+
+workload_identity = OpenAI::Auth::WorkloadIdentity.new(
+  client_id: ENV["OAUTH_CLIENT_ID"], # This is the default and can be omitted
+  identity_provider_id: ENV["IDENTITY_PROVIDER_ID"], # This is the default and can be omitted
+  service_account_id: ENV["SERVICE_ACCOUNT_ID"], # This is the default and can be omitted
+  provider: provider
+)
+
+client = OpenAI::Client.new(
+  workload_identity: workload_identity,
+)
+```
+
+### GCP Metadata Server
+
+```ruby
+provider = OpenAI::Auth::SubjectTokenProviders::GCPIDTokenProvider.new
+
+workload_identity = OpenAI::Auth::WorkloadIdentity.new(
+  client_id: ENV["OAUTH_CLIENT_ID"], # This is the default and can be omitted
+  identity_provider_id: ENV["IDENTITY_PROVIDER_ID"], # This is the default and can be omitted
+  service_account_id: ENV["SERVICE_ACCOUNT_ID"], # This is the default and can be omitted
+  provider: provider
+)
+
+client = OpenAI::Client.new(
+  workload_identity: workload_identity,
+)
+```
+
+### Custom Token Providers
+
+You can implement custom token providers by including the `OpenAI::Auth::SubjectTokenProvider` module:
+
+```ruby
+class CustomProvider
+  include OpenAI::Auth::SubjectTokenProvider
+
+  def token_type
+    OpenAI::Auth::TokenType::JWT
+  end
+
+  def get_token
+    "custom-token"
+  end
+end
+
+provider = CustomProvider.new
+
+workload_identity = OpenAI::Auth::WorkloadIdentity.new(
+  client_id: ENV["OAUTH_CLIENT_ID"], # This is the default and can be omitted
+  identity_provider_id: ENV["IDENTITY_PROVIDER_ID"], # This is the default and can be omitted
+  service_account_id: ENV["SERVICE_ACCOUNT_ID"], # This is the default and can be omitted
+  provider: provider
+)
+
+client = OpenAI::Client.new(
+  workload_identity: workload_identity,
+  organization: ENV["OPENAI_ORG_ID"],
+  project: ENV["OPENAI_PROJECT_ID"]
+)
+```
+
 ## Webhook Verification
 
 Verifying webhook signatures is _optional but encouraged_.

data/lib/openai/auth/subject_token_provider.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module OpenAI
+  module Auth
+    module SubjectTokenProvider
+      def token_type
+        raise NotImplementedError.new("#{self.class} must implement #token_type")
+      end
+
+      def get_token
+        raise NotImplementedError.new("#{self.class} must implement #get_token")
+      end
+    end
+  end
+end

data/lib/openai/auth/subject_token_providers/azure_managed_identity_token_provider.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module OpenAI
+  module Auth
+    module SubjectTokenProviders
+      class AzureManagedIdentityTokenProvider
+        include OpenAI::Auth::SubjectTokenProvider
+
+        IMDS_ENDPOINT = "http://169.254.169.254/metadata/identity/oauth2/token"
+        DEFAULT_RESOURCE = "https://management.azure.com/"
+        DEFAULT_API_VERSION = "2018-02-01"
+        DEFAULT_TIMEOUT = 10.0
+
+        def initialize(
+          resource: self.class::DEFAULT_RESOURCE,
+          object_id: nil,
+          client_id: nil,
+          msi_res_id: nil,
+          api_version: self.class::DEFAULT_API_VERSION,
+          timeout: self.class::DEFAULT_TIMEOUT
+        )
+          @resource = resource
+          @object_id = object_id
+          @client_id = client_id
+          @msi_res_id = msi_res_id
+          @api_version = api_version
+          @timeout = timeout
+        end
+
+        def token_type
+          TokenType::JWT
+        end
+
+        def get_token
+          uri = URI(self.class::IMDS_ENDPOINT)
+          params = {
+            "api-version" => @api_version,
+            "resource" => @resource
+          }
+          params["object_id"] = @object_id if @object_id
+          params["client_id"] = @client_id if @client_id
+          params["msi_res_id"] = @msi_res_id if @msi_res_id
+          uri.query = URI.encode_www_form(params)
+
+          request = Net::HTTP::Get.new(uri)
+          request["Metadata"] = "true"
+
+          response = Net::HTTP.start(
+            uri.hostname,
+            uri.port,
+            use_ssl: uri.scheme == "https",
+            open_timeout: @timeout,
+            read_timeout: @timeout
+          ) do |http|
+            http.request(request)
+          end
+
+          unless response.is_a?(Net::HTTPSuccess)
+            raise OpenAI::Errors::SubjectTokenProviderError.new(
+              message: "Azure IMDS returned #{response.code}: #{response.body}",
+              provider: "azure-imds"
+            )
+          end
+
+          data = JSON.parse(response.body, symbolize_names: true)
+
+          case data
+          in {access_token: String => token}
+            token
+          else
+            raise OpenAI::Errors::SubjectTokenProviderError.new(
+              message: "Azure IMDS response missing access_token field",
+              provider: "azure-imds"
+            )
+          end
+        rescue OpenAI::Errors::SubjectTokenProviderError
+          raise
+        rescue StandardError => e
+          raise OpenAI::Errors::SubjectTokenProviderError.new(
+            message: "Failed to fetch token from Azure IMDS: #{e.message}",
+            provider: "azure-imds",
+            cause: e
+          )
+        end
+      end
+    end
+  end
+end

data/lib/openai/auth/subject_token_providers/gcp_id_token_provider.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module OpenAI
+  module Auth
+    module SubjectTokenProviders
+      class GCPIDTokenProvider
+        include OpenAI::Auth::SubjectTokenProvider
+
+        METADATA_HOST = "metadata.google.internal"
+        DEFAULT_AUDIENCE = "https://api.openai.com/v1"
+        DEFAULT_TIMEOUT = 10.0
+
+        def initialize(
+          audience: self.class::DEFAULT_AUDIENCE,
+          timeout: self.class::DEFAULT_TIMEOUT
+        )
+          @audience = audience
+          @timeout = timeout
+        end
+
+        def token_type
+          TokenType::ID
+        end
+
+        def get_token
+          path = "/computeMetadata/v1/instance/service-accounts/default/identity"
+          uri = URI::HTTP.build(
+            host: self.class::METADATA_HOST,
+            path: path,
+            query: URI.encode_www_form("audience" => @audience)
+          )
+
+          request = Net::HTTP::Get.new(uri)
+          request["Metadata-Flavor"] = "Google"
+
+          response = Net::HTTP.start(
+            uri.hostname,
+            uri.port,
+            use_ssl: false,
+            open_timeout: @timeout,
+            read_timeout: @timeout
+          ) do |http|
+            http.request(request)
+          end
+
+          unless response.is_a?(Net::HTTPSuccess)
+            raise OpenAI::Errors::SubjectTokenProviderError.new(
+              message: "GCP Metadata Server returned #{response.code}: #{response.body}",
+              provider: "gcp-metadata"
+            )
+          end
+
+          response.body
+        rescue OpenAI::Errors::SubjectTokenProviderError
+          raise
+        rescue StandardError => e
+          raise OpenAI::Errors::SubjectTokenProviderError.new(
+            message: "Failed to fetch token from GCP Metadata Server: #{e.message}",
+            provider: "gcp-metadata",
+            cause: e
+          )
+        end
+      end
+    end
+  end
+end

data/lib/openai/auth/subject_token_providers/k8s_service_account_token_provider.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module OpenAI
+  module Auth
+    module SubjectTokenProviders
+      class K8sServiceAccountTokenProvider
+        include OpenAI::Auth::SubjectTokenProvider
+
+        DEFAULT_TOKEN_PATH = "/var/run/secrets/kubernetes.io/serviceaccount/token"
+
+        def initialize(token_path: self.class::DEFAULT_TOKEN_PATH)
+          @token_path = token_path
+        end
+
+        def token_type
+          TokenType::JWT
+        end
+
+        def get_token
+          File.read(@token_path).strip
+        rescue SystemCallError => e
+          raise OpenAI::Errors::SubjectTokenProviderError.new(
+            message: "Failed to read Kubernetes service account token from #{@token_path}: #{e.message}",
+            provider: "kubernetes",
+            cause: e
+          )
+        rescue StandardError => e
+          raise OpenAI::Errors::SubjectTokenProviderError.new(
+            message: "Unexpected error reading Kubernetes token: #{e.message}",
+            provider: "kubernetes",
+            cause: e
+          )
+        end
+      end
+    end
+  end
+end

data/lib/openai/auth/token_type.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module OpenAI
+  module Auth
+    module TokenType
+      JWT = :jwt
+      ID = :id
+    end
+  end
+end

data/lib/openai/auth/workload_identity.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module OpenAI
+  module Auth
+    class WorkloadIdentity
+      attr_reader :client_id, :identity_provider_id, :service_account_id, :provider, :refresh_buffer_seconds
+
+      def initialize(
+        client_id:,
+        identity_provider_id:,
+        service_account_id:,
+        provider:,
+        refresh_buffer_seconds: 1200
+      )
+        @client_id = client_id.to_s
+        @identity_provider_id = identity_provider_id.to_s
+        @service_account_id = service_account_id.to_s
+        @provider = provider
+        @refresh_buffer_seconds = refresh_buffer_seconds.to_i
+      end
+    end
+  end
+end

data/lib/openai/auth/workload_identity_auth.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+module OpenAI
+  module Auth
+    class WorkloadIdentityAuth
+      SUBJECT_TOKEN_TYPES = {
+        TokenType::JWT => "urn:ietf:params:oauth:token-type:jwt",
+        TokenType::ID => "urn:ietf:params:oauth:token-type:id_token"
+      }.freeze
+
+      TOKEN_EXCHANGE_GRANT_TYPE = "urn:ietf:params:oauth:grant-type:token-exchange"
+      DEFAULT_TOKEN_EXCHANGE_URL = "https://auth.openai.com/oauth/token"
+      DEFAULT_REFRESH_BUFFER_SECONDS = 1200
+
+      def initialize(
+        config,
+        organization_id,
+        token_exchange_url: DEFAULT_TOKEN_EXCHANGE_URL
+      )
+        @config = config
+        @organization_id = organization_id
+        @token_exchange_url = URI(token_exchange_url)
+
+        @cached_token = nil
+        @cached_token_expires_at_monotonic = nil
+        @cached_token_refresh_at_monotonic = nil
+        @refreshing = false
+        @mutex = Mutex.new
+        @cond_var = ConditionVariable.new
+      end
+
+      def get_token
+        @mutex.synchronize do
+          @cond_var.wait(@mutex) while @refreshing && token_unusable?
+
+          unless token_unusable? || needs_refresh?
+            return @cached_token
+          end
+
+          if @refreshing
+            @cond_var.wait(@mutex) while @refreshing
+            token = @cached_token
+            raise OpenAI::Errors::AuthenticationError, "Token refresh failed" if token_unusable?
+            return token
+          end
+
+          @refreshing = true
+        end
+
+        perform_refresh
+        @mutex.synchronize do
+          raise OpenAI::Errors::AuthenticationError, "Token refresh failed" if token_unusable?
+          @cached_token
+        end
+      end
+
+      def invalidate_token
+        @mutex.synchronize do
+          @cached_token = nil
+          @cached_token_expires_at_monotonic = nil
+          @cached_token_refresh_at_monotonic = nil
+        end
+      end
+
+      private
+
+      def perform_refresh
+        token_data = fetch_token_from_exchange
+        now = OpenAI::Internal::Util.monotonic_secs
+        expires_in = token_data.fetch(:expires_in)
+
+        @mutex.synchronize do
+          @cached_token = token_data.fetch(:id)
+          @cached_token_expires_at_monotonic = now + expires_in
+          @cached_token_refresh_at_monotonic = now + refresh_delay_seconds(expires_in)
+        end
+      ensure
+        @mutex.synchronize do
+          @refreshing = false
+          @cond_var.broadcast
+        end
+      end
+
+      def fetch_token_from_exchange
+        subject_token = @config.provider.get_token
+
+        token_type = @config.provider.token_type
+        subject_token_type = SUBJECT_TOKEN_TYPES.fetch(token_type) do
+          raise ArgumentError,
+                "Unsupported token type: #{token_type.inspect}. Supported types: #{SUBJECT_TOKEN_TYPES.keys.join(', ')}"
+        end
+
+        request = Net::HTTP::Post.new(@token_exchange_url)
+        request["Content-Type"] = "application/json"
+        request.body = JSON.generate(
+          grant_type: TOKEN_EXCHANGE_GRANT_TYPE,
+          client_id: @config.client_id,
+          subject_token: subject_token,
+          subject_token_type: subject_token_type,
+          identity_provider_id: @config.identity_provider_id,
+          service_account_id: @config.service_account_id
+        )
+
+        response = Net::HTTP.start(
+          @token_exchange_url.hostname,
+          @token_exchange_url.port,
+          use_ssl: @token_exchange_url.scheme == "https",
+          open_timeout: 5,
+          read_timeout: 5,
+          write_timeout: 5
+        ) do |http|
+          http.request(request)
+        end
+
+        handle_token_response(response)
+      end
+
+      def handle_token_response(response)
+        body = parse_response_body(response)
+
+        case response
+        in Net::HTTPBadRequest | Net::HTTPUnauthorized | Net::HTTPForbidden
+          raise OpenAI::Errors::OAuthError.new(
+            status: response.code.to_i,
+            body: body,
+            headers: response.to_hash
+          )
+        in Net::HTTPSuccess
+          {
+            id: body&.dig(:access_token),
+            expires_in: body&.dig(:expires_in)
+          }
+        else
+          raise OpenAI::Errors::APIError.new(
+            url: @token_exchange_url,
+            status: response.code.to_i,
+            headers: response.to_hash,
+            body: body,
+            message: "Token exchange failed with status #{response.code}"
+          )
+        end
+      end
+
+      def parse_response_body(response)
+        return nil if response.body.nil? || response.body.empty?
+
+        JSON.parse(response.body, symbolize_names: true)
+      rescue JSON::ParserError
+        nil
+      end
+
+      def token_unusable?
+        @cached_token.nil? || token_expired?
+      end
+
+      def token_expired?
+        return true if @cached_token_expires_at_monotonic.nil?
+
+        OpenAI::Internal::Util.monotonic_secs >= @cached_token_expires_at_monotonic
+      end
+
+      def needs_refresh?
+        return false if @cached_token_refresh_at_monotonic.nil?
+
+        OpenAI::Internal::Util.monotonic_secs >= @cached_token_refresh_at_monotonic
+      end
+
+      def refresh_delay_seconds(expires_in)
+        configured_buffer = @config.refresh_buffer_seconds || DEFAULT_REFRESH_BUFFER_SECONDS
+        effective_buffer = [configured_buffer, expires_in / 2].min
+
+        [expires_in - effective_buffer, 0].max
+      end
+    end
+  end
+end

data/lib/openai/client.rb

@@ -15,6 +15,8 @@ module OpenAI
     # Default max retry delay in seconds.
     DEFAULT_MAX_RETRY_DELAY = 8.0
 
+    WORKLOAD_IDENTITY_API_KEY_PLACEHOLDER = "workload-identity-auth"
+
     # @return [String]
     attr_reader :api_key
 
@@ -27,6 +29,10 @@ module OpenAI
     # @return [String, nil]
     attr_reader :webhook_secret
 
+    # @return [OpenAI::Auth::WorkloadIdentityAuth, nil]
+    # @api private
+    attr_reader :workload_identity_auth
+
     # Given a prompt, the model will return one or more predicted completions, and can
     # also return the probabilities of alternative tokens at each position.
     # @return [OpenAI::Resources::Completions]
@@ -116,13 +122,48 @@ module OpenAI
       {"authorization" => "Bearer #{@api_key}"}
     end
 
+    # @api private
+    private def request_replayable?(request)
+      body = request[:body]
+      return true if body.nil? || body.is_a?(String)
+      return false if body.respond_to?(:read)
+      true
+    end
+
+    # @api private
+    private def send_request(request, redirect_count:, retry_count:, send_retry_header:)
+      return super unless @workload_identity_auth
+
+      token = @workload_identity_auth.get_token
+      updated_headers = request[:headers].merge("authorization" => "Bearer #{token}")
+      updated_request = request.merge(headers: updated_headers)
+
+      begin
+        super(updated_request, redirect_count: redirect_count, retry_count: retry_count, send_retry_header: send_retry_header)
+      rescue OpenAI::Errors::AuthenticationError
+        raise unless retry_count.zero? && request_replayable?(request)
+        @workload_identity_auth.invalidate_token
+
+        fresh_token = @workload_identity_auth.get_token
+        refreshed_headers = request[:headers].merge("authorization" => "Bearer #{fresh_token}")
+        refreshed_request = request.merge(headers: refreshed_headers)
+
+        super(refreshed_request, redirect_count: redirect_count, retry_count: retry_count + 1, send_retry_header: send_retry_header)
+      end
+    end
+
     # Creates and returns a new client for interacting with the API.
     #
-    # @param api_key [String, nil] Defaults to `ENV["OPENAI_API_KEY"]`
+    # @param api_key [String, nil] Defaults to `ENV["OPENAI_API_KEY"]`.
+    #   Mutually exclusive with `workload_identity`.
+    #
+    # @param workload_identity [OpenAI::Auth::WorkloadIdentity, nil]
+    #   OAuth2 workload identity configuration for token exchange authentication.
+    #   Mutually exclusive with `api_key`.
     #
-    # @param organization [String, nil] Defaults to `ENV["OPENAI_ORG_ID"]`
+    # @param organization [String, nil] Defaults to `ENV["OPENAI_ORG_ID"]`.
     #
-    # @param project [String, nil] Defaults to `ENV["OPENAI_PROJECT_ID"]`
+    # @param project [String, nil] Defaults to `ENV["OPENAI_PROJECT_ID"]`.
     #
     # @param webhook_secret [String, nil] Defaults to `ENV["OPENAI_WEBHOOK_SECRET"]`
     #
@@ -138,6 +179,7 @@ module OpenAI
     # @param max_retry_delay [Float]
     def initialize(
       api_key: ENV["OPENAI_API_KEY"],
+      workload_identity: nil,
       organization: ENV["OPENAI_ORG_ID"],
       project: ENV["OPENAI_PROJECT_ID"],
       webhook_secret: ENV["OPENAI_WEBHOOK_SECRET"],
@@ -149,7 +191,20 @@ module OpenAI
     )
       base_url ||= "https://api.openai.com/v1"
 
-      if api_key.nil?
+      if workload_identity && api_key && api_key != WORKLOAD_IDENTITY_API_KEY_PLACEHOLDER
+        raise ArgumentError.new(
+          "The `api_key` and `workload_identity` arguments are mutually exclusive; " \
+          "only one can be passed at a time."
+        )
+      end
+
+      if workload_identity
+        @workload_identity_auth = OpenAI::Auth::WorkloadIdentityAuth.new(
+          workload_identity,
+          organization
+        )
+        api_key = WORKLOAD_IDENTITY_API_KEY_PLACEHOLDER
+      elsif api_key.nil?
         raise ArgumentError.new("api_key is required, and can be set via environ: \"OPENAI_API_KEY\"")
       end