Universal Catalog Authentication

The Universal Catalog Client supports flexible authentication for STAC APIs that require it.

Authentication Methods

Bearer Token Authentication

Most STAC APIs use Bearer token authentication:

import open_geodata_api as ogapi

client = ogapi.catalog(
    "https://api-with-auth.com/stac/",
    auth_token="your-bearer-token-here"
)

The token is automatically added to request headers as:

Authorization: Bearer your-bearer-token-here

Custom Headers

For APIs requiring additional authentication headers:

client = ogapi.catalog(
    "https://custom-api.com/stac/",
    headers={
        "X-API-Key": "your-api-key",
        "X-User-ID": "your-user-id",
        "Authorization": "Custom auth-string"
    }
)

Combined Authentication

Use both bearer token and custom headers:

client = ogapi.catalog(
    "https://secure-api.com/stac/",
    auth_token="bearer-token",
    headers={
        "X-API-Key": "additional-key",
        "X-Client-ID": "client-123"
    }
)

No Authentication

For public APIs, simply omit authentication parameters:

client = ogapi.catalog("https://earth-search.aws.element84.com/v1")

Getting Authentication Tokens

Different providers have different methods for obtaining tokens:

DLR EOC STAC Catalog

Register at https://geoservice.dlr.de
Navigate to API Access
Generate an access token
Use the token in your client:

client = ogapi.catalog(
    "https://geoservice.dlr.de/eoc/ogc/stac/v1/",
    auth_token="your-dlr-token"
)

OpenEO

Create account at openEO provider
Obtain authentication token via OpenEO Connect
Use in Universal Catalog Client:

client = ogapi.catalog(
    "https://earthengine.openeo.org/v1.0/",
    auth_token="your-openeo-token"
)

Environment Variables

Store tokens securely using environment variables:

# Set environment variable
export STAC_API_TOKEN="your-token-here"

import os
import open_geodata_api as ogapi

# Read token from environment
token = os.getenv("STAC_API_TOKEN")

client = ogapi.catalog(
    "https://secure-api.com/stac/",
    auth_token=token
)

Configuration File

Store API configurations in a file:

config.json:

{
  "dlr_eoc": {
    "url": "https://geoservice.dlr.de/eoc/ogc/stac/v1/",
    "token": "your-dlr-token"
  },
  "openeo": {
    "url": "https://earthengine.openeo.org/v1.0/",
    "token": "your-openeo-token"
  }
}

Usage:

import json
import open_geodata_api as ogapi

# Load configuration
with open("config.json") as f:
    config = json.load(f)

# Create clients from config
dlr_client = ogapi.catalog(
    config["dlr_eoc"]["url"],
    auth_token=config["dlr_eoc"]["token"]
)

openeo_client = ogapi.catalog(
    config["openeo"]["url"],
    auth_token=config["openeo"]["token"]
)

Security Best Practices

Never commit tokens to version control
Use environment variables for sensitive data
Rotate tokens regularly
Use different tokens for different environments (dev/prod)
Set appropriate timeouts to avoid hanging connections
Enable SSL verification in production (verify_ssl=True)

Troubleshooting Authentication

Issue: 401 Unauthorized

# Check if token is valid
try:
    client = ogapi.catalog(api_url, auth_token=token)
    collections = client.list_collections()
    print("✓ Authentication successful")
except Exception as e:
    print(f"✗ Authentication failed: {e}")
    print("Check: Token validity, format, expiration")

Issue: 403 Forbidden

Check if your token has the necessary permissions for the requested operation.

Issue: SSL Certificate Error

For development environments only:

client = ogapi.catalog(
    api_url,
    auth_token=token,
    verify_ssl=False  # Only for development!
)