Add a unit test and docs for the feature

Author: john-dupuy

docs/concepts.rst

@@ -259,9 +259,25 @@ created automatically by all of the object-specific I/O methods (e.g.
 :meth:`pystac.Catalog.from_file`), so most users will not need to instantiate this
 class themselves.
 
-If you require custom logic for I/O operations or would like to use a 3rd-party library
-for I/O operations (e.g. ``requests``), you can create a sub-class of
-:class:`pystac.StacIO` (or :class:`pystac.DefaultStacIO`) and customize the methods as
+If you are dealing with a STAC catalog with URIs that require authentication.
+It is possible provide auth headers (or any other customer headers) to the
+:class:`pystac.stac_io.DefaultStacIO`.
+
+.. code-block:: python
+
+  from pystac import Catalog
+  from pystac import StacIO
+
+  stac_io = StacIO.default()
+  stac_io.headers = {"Authorization": "<some-auth-header>"}
+
+  catalog = Catalog.from_file("<URI-requiring-auth>", stac_io=stac_io)
+
+
+If you require more custom logic for I/O operations or would like to use a
+3rd-party library for I/O operations (e.g. ``requests``),
+you can create a sub-class of :class:`pystac.StacIO`
+(or :class:`pystac.DefaultStacIO`) and customize the methods as
 you see fit. You can then pass instances of this custom sub-class into the ``stac_io``
 argument of most object-specific I/O methods. You can also use
 :meth:`pystac.StacIO.set_default` in your client's ``__init__.py`` file to make this

tests/test_stac_io.py

@@ -98,3 +98,19 @@ class ReportingStacIO(DefaultStacIO, DuplicateKeyReportingMixin):
                 str(excinfo.exception),
                 f'Found duplicate object name "key" in {src_href}',
             )
+
+    @unittest.mock.patch("pystac.stac_io.urlopen")
+    def test_headers_stac_io(self, urlopen_mock: unittest.mock.MagicMock) -> None:
+        stac_io = DefaultStacIO(headers={"Authorization": "api-key fake-api-key-value"})
+
+        try:
+            # note we don't care if this raises an exception, we just want to make
+            # sure urlopen was called with the appropriate headers
+            pystac.Catalog.from_file(
+                "https://example.com/catalog.json", stac_io=stac_io
+            )
+        except Exception:
+            pass
+
+        request_obj = urlopen_mock.call_args[0][0]
+        self.assertEqual(request_obj.headers, stac_io.headers)