How to Add Authentication to a STAC Catalog in Leafmap?

[pedro-cf]

Is there a way to include authentication (e.g., Basic Auth) when accessing a STAC catalog in Leafmap?

I'm currently using the following code in a Jupyter Notebook to load STAC catalogs:

import leafmap

catalogs = {
    "Element84 Earth Search": "https://earth-search.aws.element84.com/v1",
    "Microsoft Planetary Computer": "https://planetarycomputer.microsoft.com/api/stac/v1",
}
m = leafmap.Map(center=[40, -100], zoom=4)
m.set_catalog_source(catalogs)
m.add_stac_gui()
m

Some STAC catalogs require authentication (e.g., API keys, Basic Auth). I tried modifying the URL to include credentials, like this:

https://<username>:<password>@stac-api.com

However, this results in the following error:

Retrieving collections...
nonnumeric port: '<password>@stac-api.com'
expected str, bytes or os.PathLike object, not NoneType
cannot unpack non-iterable NoneType object
No collections found.

Is there a proper way to pass authentication credentials when loading a STAC catalog in Leafmap? Any guidance would be appreciated.

Thanks!

[giswqs]

The stac_custom_gui() function builds upon the pystac-client Client.open() method. You should be able to pass in any of those Client.open() parameters to stac_custom_gui() for authentication. I don't have a readily available example for this, but you can give it a try and see if it work.

Here is the list functions being called when using custom STAC catalogs.

leafmap/leafmap/toolbar.py

Line 5175 in cd24114

def stac_custom_gui(m, button_width: Optional[str] = "85px", **kwargs):

leafmap/leafmap/stac.py

Line 1316 in cd24114

def stac_collections(

leafmap/leafmap/stac.py

Line 1229 in cd24114

def stac_client(

leafmap/leafmap/stac.py

Line 1286 in cd24114

client = Client.open(

https://pystac-client.readthedocs.io/en/stable/api.html#pystac_client.Client.open

open(url, headers=None, parameters=None, ignore_conformance=None, modifier=None, request_modifier=None, stac_io=None, timeout=None)

[pedro-cf]

Can't seem to get this to work sadly... I've tried many many options...

[khalilurrrahmanridoykhan]

The custom STAC GUI can authenticate, but credentials should not be embedded in the URL. The current stac_custom_gui() forwards its keyword arguments to pystac_client.Client.open(), including headers, request_modifier, and stac_io.

For HTTP Basic authentication:

import base64
import getpass
import leafmap
from leafmap.toolbar import stac_custom_gui

username = input("STAC username: ")
password = getpass.getpass("STAC password: ")
credentials = base64.b64encode(
    f"{username}:{password}".encode("utf-8")
).decode("ascii")

headers = {
    "Authorization": f"Basic {credentials}",
}

catalogs = {
    "Private STAC": "https://stac-api.example.com",
}

m = leafmap.Map(center=[40, -100], zoom=4)
m.set_catalog_source(catalogs)
stac_custom_gui(m, headers=headers)
m

For a bearer/API token, only the header changes:

import getpass

token = getpass.getpass("STAC token: ")
headers = {"Authorization": f"Bearer {token}"}

stac_custom_gui(m, headers=headers)

This works because the same kwargs are passed both when the GUI retrieves collections and when it performs the item search:

• GUI entry point: https://github.com/opengeos/leafmap/blob/main/leafmap/toolbar.py#L5304
• Collection request: https://github.com/opengeos/leafmap/blob/main/leafmap/toolbar.py#L5695
• Search request: https://github.com/opengeos/leafmap/blob/main/leafmap/toolbar.py#L5858

A useful non-GUI check is:

from leafmap.stac import stac_client

client, catalog_id = stac_client(
    "https://stac-api.example.com",
    headers=headers,
    get_root=False,
)
print(catalog_id)
print([collection.id for collection in client.get_collections()])

Security notes:

• Do not use https://username:password@host; reserved characters can break URL parsing, and credentials may leak through notebook output, browser history, proxy logs, or exceptions.
• Do not hard-code or commit tokens. Use getpass, environment variables, or the notebook platform’s secret store.
• Authenticating the STAC metadata API does not automatically authorize a separate remote tile service. If the asset URLs are also private, they need signed URLs or a tiler/local reader that can receive the required credentials. Passing the STAC header to Client.open() alone cannot make a public TiTiler instance access a protected object store.

The public Map.add_stac_gui() convenience method currently does not expose authentication kwargs, so directly calling stac_custom_gui(m, headers=...) is the important part of this example.

[pedro-cf]

import base64
import getpass
import leafmap
from leafmap.toolbar import stac_custom_gui

username = input("STAC username: ")
password = getpass.getpass("STAC password: ")
credentials = base64.b64encode(
    f"{username}:{password}".encode("utf-8")
).decode("ascii")

headers = {
    "Authorization": f"Basic {credentials}",
}

catalogs = {
    "Private STAC": "https://stac-api.example.com",
}

m = leafmap.Map(center=[40, -100], zoom=4)
m.set_catalog_source(catalogs)
stac_custom_gui(m, headers=headers)
m

I tried this method on jupyter and it doesn't seem to work @khalilurrrahmanridoykhan

[khalilurrrahmanridoykhan]

@pedro-cf Thanks for testing it. The URL in my snippet (https://stac-api.example.com) is only a placeholder, so please replace it with the real STAC API root URL.

Before testing the GUI, could you isolate whether authentication works directly with pystac-client?

import leafmap
import pystac_client
from pystac_client import Client

print("leafmap:", leafmap.__version__)
print("pystac-client:", pystac_client.__version__)

endpoint = "https://your-real-stac-api.example/v1"
client = Client.open(endpoint, headers=headers)
print([collection.id for collection in client.get_collections()])

If this succeeds, use the same endpoint and headers in Leafmap:

m = leafmap.Map(center=[40, -100], zoom=4)
m.set_catalog_source({"Private STAC": endpoint})
stac_custom_gui(m, headers=headers)
m

If the direct Client.open() call fails, the problem is before Leafmap—commonly the API uses a bearer token, API-key header, session cookie, or OAuth flow rather than HTTP Basic Auth, or the supplied URL is not the STAC API root. If Client.open() succeeds but the GUI fails, please share the full traceback plus the two package versions above. Updating both packages and restarting the Jupyter kernel is also worth trying:

pip install --upgrade leafmap pystac-client

Please redact the endpoint if private and do not post the username, password, token, or generated Authorization header.

[pedro-cf]

I ran the following code in jupyter and the collections are successfully printed:

from getpass import getpass
import base64
import leafmap
import pystac_client
from pystac_client import Client
from leafmap.toolbar import stac_custom_gui

endpoint = getpass("STAC endpoint:")
username = getpass("STAC username:")
password = getpass("STAC password:")

token = base64.b64encode(
    f"{username}:{password}".encode()
).decode()

headers = {
    "Authorization": f"Basic {token}"
}


print("leafmap:", leafmap.__version__)
print("pystac-client:", pystac_client.__version__)


client = Client.open(endpoint, headers=headers)
print([collection.id for collection in client.get_collections()])

STAC endpoint: ········
STAC username: ········
STAC password: ········


leafmap: 0.63.0
pystac-client: 0.9.0
[ 'ee0cfb940bfe4b428ba929a7405c7954', 'cbm-52b70aa317b143d5993dddad37de1762', '761a54b573324cad91244a7f6e73d50f']

But when running the map:

m = leafmap.Map(center=[40, -100], zoom=4)
m.set_catalog_source({"Private STAC": endpoint})
stac_custom_gui(m, headers=headers)
m

And clicking the 'collections' button, no collections are displayed in the collections dropdown:

[khalilurrrahmanridoykhan]

@pedro-cf Thank you—this result confirms that your endpoint and Basic Auth header are correct. I traced the Leafmap 0.63.0 GUI path and found the inconsistency.

The endpoint-change handler calls:

stac_collections(..., get_root=False, **kwargs)

so the authenticated pystac-client request can work. However, clicking Collections calls stac_collections() without get_root=False, and the Items action follows the same root-resolution path. stac_client() then calls stac_root_link(), whose initial requests.get(url) does not currently receive the headers. A protected endpoint therefore fails during that unauthenticated root lookup before Client.open(..., headers=headers) is reached.

So this is a Leafmap authentication propagation issue, not a problem with your credentials.

As a temporary local test, change this line inside leafmap/stac.py in stac_client():

root = stac_root_link(url, return_col_id=return_col_id)

to:

root = stac_root_link(
    url,
    return_col_id=return_col_id,
    headers=headers,
    params=parameters,
)

Then restart the Jupyter kernel and rerun the notebook. Please keep your credentials out of the source file—the change only forwards the existing request headers.

This should be fixed upstream so authenticated headers are consistently used during root discovery as well as collection and item requests.