ruby-oauth · pboling · Aug 31, 2025 · Aug 31, 2025
diff --git a/.rubocop_gradual.lock b/.rubocop_gradual.lock
@@ -34,7 +34,7 @@
     [69, 15, 38, "RSpec/ContextWording: Context description should match /^when\\b/, /^with\\b/, or /^without\\b/.", 1480816240],
     [79, 13, 23, "RSpec/ContextWording: Context description should match /^when\\b/, /^with\\b/, or /^without\\b/.", 2314399065]
   ],
-  "spec/oauth2/client_spec.rb:292714281": [
+  "spec/oauth2/client_spec.rb:2143306493": [
     [6, 1, 29, "RSpec/SpecFilePathFormat: Spec path should end with `o_auth2/client*_spec.rb`.", 439549885],
     [175, 7, 492, "RSpec/NoExpectationExample: No expectation found in this example.", 1272021224],
     [194, 7, 592, "RSpec/NoExpectationExample: No expectation found in this example.", 3428877205],

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -8,6 +8,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 - improved documentation by @pboling
 - Document Mutual TLS (mTLS) usage with example in README (connection_opts.ssl client_cert/client_key and auth_scheme: :tls_client_auth)
+- Document usage of flat query params using Faraday::FlatParamsEncoder, with example URI, in README
+- Spec: verify flat params are preserved with Faraday::FlatParamsEncoder (skips on Faraday without FlatParamsEncoder)
 - documentation notes in code comments and README highlighting OAuth 2.1 differences, with references, such as:
   - PKCE required for auth code,
   - exact redirect URI match,

diff --git a/README.md b/README.md
@@ -991,6 +991,48 @@ client = OAuth2::Client.new(
 end
 ```
 
+##### Using flat query params (Faraday::FlatParamsEncoder)
+
+Some APIs expect repeated key parameters to be sent as flat params rather than arrays. Faraday provides FlatParamsEncoder for this purpose. You can configure the oauth2 client to use it when building requests.
+
+```ruby
+require "faraday"
+
+client = OAuth2::Client.new(
+  id,
+  secret,
+  site: "https://api.example.com",
+  # Pass Faraday connection options to make FlatParamsEncoder the default
+  connection_opts: {
+    request: {params_encoder: Faraday::FlatParamsEncoder},
+  },
+) do |faraday|
+  faraday.request(:url_encoded)
+  faraday.adapter(:net_http)
+end
+
+access = client.client_credentials.get_token
+
+# Example of a GET with two flat filter params (not an array):
+# Results in: ?filter=order.clientCreatedTime%3E1445006997000&filter=order.clientCreatedTime%3C1445611797000
+resp = access.get(
+  "/v1/orders",
+  params: {
+    # Provide the values as an array; FlatParamsEncoder expands them as repeated keys
+    filter: [
+      "order.clientCreatedTime>1445006997000",
+      "order.clientCreatedTime<1445611797000",
+    ],
+  },
+)
+```
+
+If you instead need to build a raw Faraday connection yourself, the equivalent configuration is:
+
+```ruby
+conn = Faraday.new("https://api.example.com", request: {params_encoder: Faraday::FlatParamsEncoder})
+```
+
 #### Redirection
 
 The library follows up to `max_redirects` (default 5).

diff --git a/docs/OAuth2.html b/docs/OAuth2.html
@@ -415,7 +415,7 @@ <h3 class="signature first" id="configure-class_method">
 </div>
 
       <div id="footer">
-  Generated on Sun Aug 31 04:29:08 2025 by
+  Generated on Sun Aug 31 04:57:44 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.5).
 </div>

diff --git a/docs/OAuth2/AccessToken.html b/docs/OAuth2/AccessToken.html
@@ -3069,7 +3069,7 @@ <h3 class="signature " id="to_hash-instance_method">
 </div>
 
       <div id="footer">
-  Generated on Sun Aug 31 04:29:08 2025 by
+  Generated on Sun Aug 31 04:57:44 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.5).
 </div>

diff --git a/docs/OAuth2/Authenticator.html b/docs/OAuth2/Authenticator.html
@@ -883,7 +883,7 @@ <h3 class="signature first" id="apply-instance_method">
 </div>
 
       <div id="footer">
-  Generated on Sun Aug 31 04:29:08 2025 by
+  Generated on Sun Aug 31 04:57:44 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.5).
 </div>

diff --git a/docs/OAuth2/Client.html b/docs/OAuth2/Client.html
@@ -2656,7 +2656,7 @@ <h3 class="signature " id="token_url-instance_method">
 </div>
 
       <div id="footer">
-  Generated on Sun Aug 31 04:29:08 2025 by
+  Generated on Sun Aug 31 04:57:44 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.5).
 </div>

diff --git a/docs/OAuth2/Error.html b/docs/OAuth2/Error.html
@@ -772,7 +772,7 @@ <h3 class="signature " id="response-instance_method">
 </div>
 
       <div id="footer">
-  Generated on Sun Aug 31 04:29:08 2025 by
+  Generated on Sun Aug 31 04:57:44 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.5).
 </div>

diff --git a/docs/OAuth2/FilteredAttributes.html b/docs/OAuth2/FilteredAttributes.html
@@ -335,7 +335,7 @@ <h3 class="signature first" id="inspect-instance_method">
 </div>
 
       <div id="footer">
-  Generated on Sun Aug 31 04:29:08 2025 by
+  Generated on Sun Aug 31 04:57:44 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.5).
 </div>

diff --git a/docs/OAuth2/FilteredAttributes/ClassMethods.html b/docs/OAuth2/FilteredAttributes/ClassMethods.html
@@ -280,7 +280,7 @@ <h3 class="signature " id="filtered_attributes-instance_method">
 </div>
 
       <div id="footer">
-  Generated on Sun Aug 31 04:29:08 2025 by
+  Generated on Sun Aug 31 04:57:44 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.5).
 </div>

diff --git a/docs/OAuth2/Response.html b/docs/OAuth2/Response.html
@@ -1619,7 +1619,7 @@ <h3 class="signature " id="status-instance_method">
 </div>
 
       <div id="footer">
-  Generated on Sun Aug 31 04:29:08 2025 by
+  Generated on Sun Aug 31 04:57:44 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.5).
 </div>

diff --git a/docs/OAuth2/Strategy.html b/docs/OAuth2/Strategy.html
@@ -107,7 +107,7 @@ <h2>Defined Under Namespace</h2>
 </div>
 
       <div id="footer">
-  Generated on Sun Aug 31 04:29:08 2025 by
+  Generated on Sun Aug 31 04:57:44 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.5).
 </div>

diff --git a/docs/OAuth2/Strategy/Assertion.html b/docs/OAuth2/Strategy/Assertion.html
@@ -481,7 +481,7 @@ <h3 class="signature " id="get_token-instance_method">
 </div>
 
       <div id="footer">
-  Generated on Sun Aug 31 04:29:08 2025 by
+  Generated on Sun Aug 31 04:57:44 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.5).
 </div>

diff --git a/docs/OAuth2/Strategy/AuthCode.html b/docs/OAuth2/Strategy/AuthCode.html
@@ -483,7 +483,7 @@ <h3 class="signature " id="get_token-instance_method">
 </div>
 
       <div id="footer">
-  Generated on Sun Aug 31 04:29:08 2025 by
+  Generated on Sun Aug 31 04:57:44 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.5).
 </div>

diff --git a/docs/OAuth2/Strategy/Base.html b/docs/OAuth2/Strategy/Base.html
@@ -195,7 +195,7 @@ <h3 class="signature first" id="initialize-instance_method">
 </div>
 
       <div id="footer">
-  Generated on Sun Aug 31 04:29:08 2025 by
+  Generated on Sun Aug 31 04:57:44 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.5).
 </div>

diff --git a/docs/OAuth2/Strategy/ClientCredentials.html b/docs/OAuth2/Strategy/ClientCredentials.html
@@ -343,7 +343,7 @@ <h3 class="signature " id="get_token-instance_method">
 </div>
 
       <div id="footer">
-  Generated on Sun Aug 31 04:29:08 2025 by
+  Generated on Sun Aug 31 04:57:44 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.5).
 </div>

diff --git a/docs/OAuth2/Strategy/Implicit.html b/docs/OAuth2/Strategy/Implicit.html
@@ -420,7 +420,7 @@ <h3 class="signature " id="get_token-instance_method">
 </div>
 
       <div id="footer">
-  Generated on Sun Aug 31 04:29:08 2025 by
+  Generated on Sun Aug 31 04:57:44 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.5).
 </div>

diff --git a/docs/OAuth2/Strategy/Password.html b/docs/OAuth2/Strategy/Password.html
@@ -374,7 +374,7 @@ <h3 class="signature " id="get_token-instance_method">
 </div>
 
       <div id="footer">
-  Generated on Sun Aug 31 04:29:08 2025 by
+  Generated on Sun Aug 31 04:57:44 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.5).
 </div>

diff --git a/docs/OAuth2/Version.html b/docs/OAuth2/Version.html
@@ -111,7 +111,7 @@ <h2>
 </div>
 
       <div id="footer">
-  Generated on Sun Aug 31 04:29:08 2025 by
+  Generated on Sun Aug 31 04:57:44 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.5).
 </div>

diff --git a/docs/_index.html b/docs/_index.html
@@ -366,7 +366,7 @@ <h2>Namespace Listing A-Z</h2>
 </div>
 
       <div id="footer">
-  Generated on Sun Aug 31 04:29:07 2025 by
+  Generated on Sun Aug 31 04:57:43 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.5).
 </div>

diff --git a/docs/file.CHANGELOG.html b/docs/file.CHANGELOG.html
@@ -67,6 +67,9 @@ <h2 id="unreleased"><a href="https://gitlab.com/ruby-oauth/oauth2/-/compare/v2.0
 <h3 id="added">Added</h3>
 <ul>
   <li>improved documentation by @pboling</li>
+  <li>Document Mutual TLS (mTLS) usage with example in README (connection_opts.ssl client_cert/client_key and auth_scheme: :tls_client_auth)</li>
+  <li>Document usage of flat query params using Faraday::FlatParamsEncoder, with example URI, in README</li>
+  <li>Spec: verify flat params are preserved with Faraday::FlatParamsEncoder (skips on Faraday without FlatParamsEncoder)</li>
   <li>documentation notes in code comments and README highlighting OAuth 2.1 differences, with references, such as:
     <ul>
       <li>PKCE required for auth code,</li>
@@ -1245,7 +1248,7 @@ <h2 id="001---2010-04-22">
 </div></div>
 
       <div id="footer">
-  Generated on Sun Aug 31 04:29:08 2025 by
+  Generated on Sun Aug 31 04:57:43 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.5).
 </div>

diff --git a/docs/file.CITATION.html b/docs/file.CITATION.html
@@ -82,7 +82,7 @@
 </div></div>
 
       <div id="footer">
-  Generated on Sun Aug 31 04:29:08 2025 by
+  Generated on Sun Aug 31 04:57:44 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.5).
 </div>

diff --git a/docs/file.CODE_OF_CONDUCT.html b/docs/file.CODE_OF_CONDUCT.html
@@ -191,7 +191,7 @@ <h2 id="attribution">Attribution</h2>
 </div></div>
 
       <div id="footer">
-  Generated on Sun Aug 31 04:29:08 2025 by
+  Generated on Sun Aug 31 04:57:43 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.5).
 </div>

diff --git a/docs/file.CONTRIBUTING.html b/docs/file.CONTRIBUTING.html
@@ -274,7 +274,7 @@ <h4 id="manual-process">Manual process</h4>
 </div></div>
 
       <div id="footer">
-  Generated on Sun Aug 31 04:29:08 2025 by
+  Generated on Sun Aug 31 04:57:44 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.5).
 </div>

diff --git a/docs/file.FUNDING.html b/docs/file.FUNDING.html
@@ -104,7 +104,7 @@ <h1 id="another-way-to-support-open-source-software">Another Way to Support Open
 </div></div>
 
       <div id="footer">
-  Generated on Sun Aug 31 04:29:08 2025 by
+  Generated on Sun Aug 31 04:57:44 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.5).
 </div>

diff --git a/docs/file.LICENSE.html b/docs/file.LICENSE.html
@@ -60,7 +60,7 @@
       <div id="content"><div id='filecontents'>MIT License<br><br>Copyright (c) 2017-2025 Peter H. Boling, of Galtzo.com, and oauth2 contributors<br>Copyright (c) 2011-2013 Michael Bleigh and Intridea, Inc.<br><br>Permission is hereby granted, free of charge, to any person obtaining a copy<br>of this software and associated documentation files (the "Software"), to deal<br>in the Software without restriction, including without limitation the rights<br>to use, copy, modify, merge, publish, distribute, sublicense, and/or sell<br>copies of the Software, and to permit persons to whom the Software is<br>furnished to do so, subject to the following conditions:<br><br>The above copyright notice and this permission notice shall be included in all<br>copies or substantial portions of the Software.<br><br>THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR<br>IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,<br>FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE<br>AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER<br>LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,<br>OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE<br>SOFTWARE.</div></div>
 
       <div id="footer">
-  Generated on Sun Aug 31 04:29:08 2025 by
+  Generated on Sun Aug 31 04:57:44 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.5).
 </div>

diff --git a/docs/file.OIDC.html b/docs/file.OIDC.html
@@ -247,7 +247,7 @@ <h2 id="raw-oidc-with-ruby-oauthoauth2">Raw OIDC with ruby-oauth/oauth2</h2>
 </div></div>
 
       <div id="footer">
-  Generated on Sun Aug 31 04:29:08 2025 by
+  Generated on Sun Aug 31 04:57:44 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.5).
 </div>