boldsign 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cbe0865fb65380ebdee0b2a2ccca3804a3cac90639d93778cc7350ca202294d4
-  data.tar.gz: 93dc1c1e373d29ea4bf07af0622da0662fd5d6d0b044e317ce6e69ceb442743b
+  metadata.gz: 9fc744443078d2ffab4156204b7921ef617c3788d373253956a0fe9f3455a14a
+  data.tar.gz: 133c334403bb3a2655f61ab7c14f8d9d75c9e3adf5212f9bdf7e69811a2cda2a
 SHA512:
-  metadata.gz: 27eb15a5d89fe793cbae44f5e67ebb6b1c52eb71313e2ef677e57b004384f40e552dcebd53525c86c7ddb14d30f3fb278fe9e955aeadb39b5a2d573eb309704a
-  data.tar.gz: 6d11a55a16fb6f553e5136dde756baa972ebed48e0b6a5ebeac50cc3abf27b3d0ca2d2bc47103fe42ea2c3933c3a4a2c9f2d8704ed7ebd546d60c7cee69ca953
+  metadata.gz: 96e5622f76bf23b2df6be9663542fb0db5da070f40480e6649960da33d336c14afcafc36c308b5dad867fa4ce90ab3faf574c3c956011c330c7599713cf3afe2
+  data.tar.gz: 640539d3b260f4b50de92bddca66ed45a794c0c54c722d32d807134eee505d06f737542d077403ab71f5699f23e106567d1bf19dfb4954420398904e9cd756e2

data/CHANGELOG.md

@@ -7,6 +7,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.0] — 2026-06-02
+
+### Added
+- OAuth 2.0 authentication via the **client credentials** grant. Configure
+  `client_id` / `client_secret` (on `Boldsign.configure` or `Client.new`) and
+  the client fetches a bearer token from the region's account host
+  (`https://account.boldsign.com/connect/token` for `:us`), caches it until
+  shortly before `expires_in` lapses, and sends `Authorization: Bearer …`
+  instead of `X-API-KEY`. Token fetches are mutex-guarded for shared clients.
+- `scope:` (defaults to `BoldSign.Documents.All`) and `token_url:` options to
+  override the requested scope and token endpoint.
+- `access_token:` option to supply a pre-obtained bearer token that is used
+  as-is (not refreshed).
+- `Boldsign::AccessToken` encapsulating the client-credentials token lifecycle.
+- `TOKEN_REGIONS` / `DEFAULT_TOKEN_BASE_URL` constants and `Client#auth_mode`.
+
+### Changed
+- `Client.new` no longer requires an API key. It accepts any one of
+  `client_id`/`client_secret`, `access_token`, or `api_key`, and raises
+  `ConfigurationError` only when none is provided. The API-key path is
+  unchanged, so existing `api_key:` callers keep working.
+
 ## [0.4.0] — 2026-05-22
 
 ### Changed
@@ -68,5 +90,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - 100% line and branch test coverage enforced via SimpleCov.
 - GitHub Actions CI on Ruby 3.4 and 4.0.
 
-[Unreleased]: https://github.com/kleinjm/boldsign-ruby/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/kleinjm/boldsign-ruby/compare/v0.5.0...HEAD
+[0.5.0]: https://github.com/kleinjm/boldsign-ruby/compare/v0.4.0...v0.5.0
 [0.1.0]: https://github.com/kleinjm/boldsign-ruby/releases/tag/v0.1.0

data/README.md

@@ -17,6 +17,32 @@ gem "boldsign"
 
 ## Configuration
 
+The client authenticates with either an API key or OAuth 2.0.
+
+### OAuth 2.0 (client credentials)
+
+Register an OAuth app in the BoldSign dashboard (API → OAuth Apps) and configure
+its `client_id` / `client_secret`. The client fetches a bearer token from the
+region's account host, caches it until shortly before it expires, and refreshes
+automatically — no token plumbing on your side.
+
+```ruby
+Boldsign.configure do |c|
+  c.client_id     = ENV["BOLDSIGN_CLIENT_ID"]
+  c.client_secret = ENV["BOLDSIGN_CLIENT_SECRET"]
+  c.region        = :us   # :us, :eu, :ca, :au
+  # c.scope       = "BoldSign.Documents.All"  # optional; empty grants all the app allows
+end
+```
+
+You can also pass a token you obtained yourself (used as-is, not refreshed):
+
+```ruby
+Boldsign::Client.new(access_token: "…", region: :us)
+```
+
+### API key
+
 ```ruby
 Boldsign.configure do |c|
   c.api_key = ENV["BOLDSIGN_API_KEY"]
@@ -30,14 +56,17 @@ Or instantiate a client directly:
 client = Boldsign::Client.new(api_key: "…", region: :us)
 ```
 
-Region base URLs:
+Region hosts:
+
+| Region | API base URL | OAuth account host |
+| ------ | ------------ | ------------------ |
+| `:us`  | `https://api.boldsign.com` | `https://account.boldsign.com` |
+| `:eu`  | `https://api-eu.boldsign.com` | `https://account-eu.boldsign.com` |
+| `:ca`  | `https://api-ca.boldsign.com` | `https://account-ca.boldsign.com` |
+| `:au`  | `https://api-au.boldsign.com` | `https://account-au.boldsign.com` |
 
-| Region | URL |
-| ------ | --- |
-| `:us`  | `https://api.boldsign.com` |
-| `:eu`  | `https://api-eu.boldsign.com` |
-| `:ca`  | `https://api-ca.boldsign.com` |
-| `:au`  | `https://api-au.boldsign.com` |
+The token endpoint is the account host + `/connect/token`; override the full URL
+with `token_url:` if a region differs.
 
 ## Usage
 

data/lib/boldsign/access_token.rb

@@ -0,0 +1,95 @@
+module Boldsign
+  # Fetches and caches an OAuth 2.0 access token using the client credentials
+  # grant (server-to-server; no user interaction).
+  #
+  # A single instance is shared by a {Client} and may be hit from multiple
+  # threads, so token reads/refreshes are guarded by a mutex. The token is
+  # cached until shortly before it expires ({EXPIRY_LEEWAY_SECONDS}), then a new
+  # one is requested on the next call. The client credentials grant does not
+  # issue refresh tokens — expiry is handled by re-requesting.
+  #
+  # @see https://developers.boldsign.com/authentication/oauth-2-0/
+  class AccessToken
+    # Token endpoint path, appended to the region's account host.
+    TOKEN_PATH = "/connect/token".freeze
+
+    # Default scope requested for the access token. Covers the document /
+    # signature endpoints this gem is primarily used for. Pass a different
+    # `scope:` to request others (an empty scope grants all the app is allowed).
+    DEFAULT_SCOPE = "BoldSign.Documents.All".freeze
+
+    # Refresh this many seconds before the token actually expires, so an
+    # in-flight request never carries a token that lapses server-side mid-call.
+    EXPIRY_LEEWAY_SECONDS = 60
+
+    # Fallback lifetime (seconds) when the token response omits `expires_in`.
+    DEFAULT_EXPIRES_IN = 3600
+
+    # @param client_id [String] OAuth app client ID.
+    # @param client_secret [String] OAuth app client secret.
+    # @param token_url [String] Full token endpoint URL (host + {TOKEN_PATH}).
+    # @param scope [String] OAuth scope to request.
+    # @param adapter [Symbol] Faraday adapter.
+    def initialize(client_id:, client_secret:, token_url:, scope: DEFAULT_SCOPE,
+                   adapter: Faraday.default_adapter)
+      @client_id = client_id
+      @client_secret = client_secret
+      @token_url = token_url
+      @scope = scope
+      @adapter = adapter
+      @mutex = Mutex.new
+    end
+
+    # @return [String] a currently-valid bearer token, fetching or refreshing
+    #   one if the cached token is missing or near expiry.
+    def value
+      @mutex.synchronize do
+        refresh! if expired?
+        @token
+      end
+    end
+
+    private
+
+    def expired?
+      @token.nil? || Time.now >= @expires_at
+    end
+
+    def refresh!
+      response = connection.post(@token_url) do |req|
+        req.headers["Content-Type"] = "application/x-www-form-urlencoded"
+        req.body = URI.encode_www_form(
+          grant_type: "client_credentials",
+          client_id: @client_id,
+          client_secret: @client_secret,
+          scope: @scope
+        )
+      end
+      raise_token_error(response) unless response.success?
+
+      body = JSON.parse(response.body)
+      @token = body["access_token"]
+      expires_in = (body["expires_in"] || DEFAULT_EXPIRES_IN).to_i
+      @expires_at = Time.now + expires_in - EXPIRY_LEEWAY_SECONDS
+    end
+
+    def connection
+      Faraday.new do |f|
+        f.adapter @adapter
+      end
+    end
+
+    def raise_token_error(response)
+      body = begin
+        JSON.parse(response.body)
+      rescue StandardError
+        response.body
+      end
+      message = body.is_a?(Hash) ? (body["error_description"] || body["error"] || body.to_s) : body.to_s
+      raise AuthenticationError.new(
+        "BoldSign OAuth token request failed (#{response.status}): #{message}",
+        status: response.status, body: body, response: response
+      )
+    end
+  end
+end

data/lib/boldsign/client.rb

@@ -8,9 +8,21 @@ module Boldsign
   # Low-level verb methods ({#get}, {#post}, {#put}, {#patch}, {#delete},
   # {#download}) are also available for hitting any endpoint directly.
   #
-  # @example
+  # Authenticates with either an API key (`X-API-KEY`) or OAuth 2.0
+  # (`Authorization: Bearer`). For OAuth, pass `client_id`/`client_secret` and
+  # the client fetches + caches a token via the client credentials grant; or
+  # pass a `access_token` you obtained yourself.
+  #
+  # @example API key
   #   client = Boldsign::Client.new(api_key: ENV["BOLDSIGN_API_KEY"], region: :us)
   #   client.documents.send_document(title: "NDA", signers: [...])
+  #
+  # @example OAuth client credentials
+  #   client = Boldsign::Client.new(
+  #     client_id: ENV["BOLDSIGN_CLIENT_ID"],
+  #     client_secret: ENV["BOLDSIGN_CLIENT_SECRET"],
+  #     region: :us
+  #   )
   class Client
     # Default region (US).
     DEFAULT_BASE_URL = "https://api.boldsign.com".freeze
@@ -18,25 +30,50 @@ module Boldsign
     # User-Agent header value sent on every request.
     USER_AGENT = "boldsign-ruby/#{Boldsign::VERSION}".freeze
 
-    # @return [String] the API key in use.
+    # @return [String, nil] the API key in use, when authenticating via API key.
     attr_reader :api_key
 
+    # @return [Symbol] the resolved auth mode (`:api_key`, `:oauth`, or `:bearer`).
+    attr_reader :auth_mode
+
     # @return [String] the resolved base URL (region or explicit override).
     attr_reader :base_url
 
     # @param api_key [String, nil] BoldSign API key. Falls back to `ENV["BOLDSIGN_API_KEY"]`.
-    # @param region [Symbol, nil] One of `:us`, `:eu`, `:ca`, `:au`. Ignored if `base_url` is given.
-    # @param base_url [String, nil] Explicit base URL override.
+    # @param client_id [String, nil] OAuth app client ID (enables the client credentials grant).
+    # @param client_secret [String, nil] OAuth app client secret (required with `client_id`).
+    # @param access_token [String, nil] A pre-obtained OAuth bearer token (used as-is, not refreshed).
+    # @param scope [String, nil] OAuth scope to request (defaults to {AccessToken::DEFAULT_SCOPE}).
+    # @param token_url [String, nil] Override for the full OAuth token endpoint URL.
+    # @param region [Symbol, nil] One of `:us`, `:eu`, `:ca`, `:au`. Ignored if `base_url`/`token_url` is given.
+    # @param base_url [String, nil] Explicit API base URL override.
     # @param adapter [Symbol] Faraday adapter (defaults to `Faraday.default_adapter`).
     # @param logger [Logger, nil] Optional logger; when present, Faraday's logger middleware is enabled.
-    # @raise [ConfigurationError] when no API key is available.
-    def initialize(api_key: nil, region: nil, base_url: nil, adapter: Faraday.default_adapter, logger: nil)
+    # @raise [ConfigurationError] when no usable credentials are provided.
+    def initialize(api_key: nil, client_id: nil, client_secret: nil, access_token: nil,
+                   scope: nil, token_url: nil, region: nil, base_url: nil,
+                   adapter: Faraday.default_adapter, logger: nil)
       @api_key = api_key || ENV["BOLDSIGN_API_KEY"]
-      raise ConfigurationError, "Missing BoldSign API key" if @api_key.nil? || @api_key.empty?
-
+      @static_access_token = access_token
       @base_url = base_url || Boldsign::REGIONS[region&.to_sym] || DEFAULT_BASE_URL
       @adapter = adapter
       @logger = logger
+
+      if present?(client_id) && present?(client_secret)
+        @auth_mode = :oauth
+        @access_token = AccessToken.new(
+          client_id: client_id, client_secret: client_secret,
+          token_url: token_url || default_token_url(region),
+          scope: scope || AccessToken::DEFAULT_SCOPE, adapter: adapter
+        )
+      elsif present?(@static_access_token)
+        @auth_mode = :bearer
+      elsif present?(@api_key)
+        @auth_mode = :api_key
+      else
+        raise ConfigurationError,
+              "Missing BoldSign credentials: provide client_id/client_secret, access_token, or api_key"
+      end
     end
 
     # @return [Resources::Brand]
@@ -137,7 +174,7 @@ module Boldsign
       Faraday.new(url: @base_url) do |f|
         f.request :multipart if multipart
         f.request :url_encoded
-        f.headers["X-API-KEY"] = @api_key
+        apply_auth(f.headers)
         f.headers["Accept"] = "application/json"
         f.headers["User-Agent"] = USER_AGENT
         f.response :logger, @logger if @logger
@@ -145,6 +182,27 @@ module Boldsign
       end
     end
 
+    def apply_auth(headers)
+      if @auth_mode == :api_key
+        headers["X-API-KEY"] = @api_key
+      else
+        headers["Authorization"] = "Bearer #{bearer_token}"
+      end
+    end
+
+    def bearer_token
+      @auth_mode == :oauth ? @access_token.value : @static_access_token
+    end
+
+    def present?(value)
+      !value.nil? && !value.empty?
+    end
+
+    def default_token_url(region)
+      base = Boldsign::TOKEN_REGIONS[region&.to_sym] || Boldsign::DEFAULT_TOKEN_BASE_URL
+      "#{base}#{AccessToken::TOKEN_PATH}"
+    end
+
     def parse_body(response)
       return nil if response.body.nil? || response.body.empty?
       content_type = response.headers["content-type"].to_s

data/lib/boldsign/version.rb

@@ -1,3 +1,3 @@
 module Boldsign
-  VERSION = "0.4.0"
+  VERSION = "0.5.0"
 end

data/lib/boldsign.rb

@@ -1,10 +1,12 @@
 require "faraday"
 require "faraday/multipart"
 require "json"
+require "uri"
 
 require_relative "boldsign/version"
 require_relative "boldsign/error"
 require_relative "boldsign/case_convert"
+require_relative "boldsign/access_token"
 require_relative "boldsign/client"
 require_relative "boldsign/resource"
 require_relative "boldsign/resources/brand"
@@ -24,10 +26,11 @@ require_relative "boldsign/resources/user"
 # Configure once at boot and access a shared {Client} via {Boldsign.client}, or
 # instantiate {Client} directly when you need multiple credentials/regions.
 #
-# @example Configure and use the shared client
+# @example Configure with OAuth and use the shared client
 #   Boldsign.configure do |c|
-#     c.api_key = ENV["BOLDSIGN_API_KEY"]
-#     c.region  = :us
+#     c.client_id     = ENV["BOLDSIGN_CLIENT_ID"]
+#     c.client_secret = ENV["BOLDSIGN_CLIENT_SECRET"]
+#     c.region        = :us
 #   end
 #   Boldsign.client.documents.list
 module Boldsign
@@ -39,10 +42,37 @@ module Boldsign
     au: "https://api-au.boldsign.com"
   }.freeze
 
+  # Region → account host map for the OAuth token endpoint. Non-US hosts follow
+  # BoldSign's regional naming; override with `token_url:` if a region differs.
+  TOKEN_REGIONS = {
+    us: "https://account.boldsign.com",
+    eu: "https://account-eu.boldsign.com",
+    ca: "https://account-ca.boldsign.com",
+    au: "https://account-au.boldsign.com"
+  }.freeze
+
+  # Default account host (US) for the OAuth token endpoint.
+  DEFAULT_TOKEN_BASE_URL = "https://account.boldsign.com".freeze
+
   class << self
     # @return [String, nil] API key used by the shared {client}.
     attr_accessor :api_key
 
+    # @return [String, nil] OAuth app client ID used by the shared {client}.
+    attr_accessor :client_id
+
+    # @return [String, nil] OAuth app client secret used by the shared {client}.
+    attr_accessor :client_secret
+
+    # @return [String, nil] Pre-obtained OAuth bearer token (used as-is, not refreshed).
+    attr_accessor :access_token
+
+    # @return [String, nil] OAuth scope to request (defaults to {AccessToken::DEFAULT_SCOPE}).
+    attr_accessor :scope
+
+    # @return [String, nil] Override for the full OAuth token endpoint URL.
+    attr_accessor :token_url
+
     # @return [Symbol, nil] Region key (`:us`, `:eu`, `:ca`, `:au`).
     attr_accessor :region
 
@@ -58,7 +88,11 @@ module Boldsign
 
     # @return [Client] memoized shared client built from module-level config.
     def client
-      @client ||= Client.new(api_key: api_key, region: region, base_url: base_url)
+      @client ||= Client.new(
+        api_key: api_key, client_id: client_id, client_secret: client_secret,
+        access_token: access_token, scope: scope, token_url: token_url,
+        region: region, base_url: base_url
+      )
     end
 
     # Clears the memoized shared client so the next call to {client} rebuilds it.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: boldsign
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - James Klein
@@ -92,6 +92,7 @@ files:
 - README.md
 - boldsign.gemspec
 - lib/boldsign.rb
+- lib/boldsign/access_token.rb
 - lib/boldsign/case_convert.rb
 - lib/boldsign/client.rb
 - lib/boldsign/error.rb