Authentication & Quotas

Set up authentication for HDA API access and understand roles and quota limits.

Authentication Overview

The HDA API uses a tiered authentication approach:

Public Access

No authentication required

  • Services discovery (/services)

  • Collections metadata (/stac/v2/collections)

  • API capabilities and conformance

Perfect for exploration and integration testing

Authenticated Access

DestinE account required

  • Data items search and browsing

  • Data file downloads and streaming

  • Private/restricted collections

  • ECMWF data ordering

Required for actual data access

Extended Permissions

Additional approval required

  • Specialized restricted collections

  • Higher quotas and rate limits

  • Digital Twin (DT) Outputs datasets

Follow the HDA roles guide on My DataLake Services

Important

Special Case: DestinE Digital Twin Outputs

For Digital Twin Outputs datasets specifically, use the DESP Platform Contact Form instead. These datasets require approval from the European Commission and cannot be requested through My DataLake Services.

Quotas & Rate Limits

Default Quotas (all DestinE users):

Limit Type

Default Value

Description

Request Rate

4 req/second

Maximum API calls per second

Bandwidth

20 Mbps

Download speed per connection

Monthly Transfer

6 TB

Total data transfer per month

Extended Quotas: For higher limits, request through My DataLake Service.

Authentication Methods

Choose your preferred authentication approach based on your use case:

Best for: Python workflows, automatic token management

EODAG handles authentication automatically:

import os
from eodag import EODataAccessGateway

# Set credentials (EODAG reads these automatically)
os.environ['EODAG_DEDL_AUTH_CREDENTIALS_USERNAME'] = 'your_username'
os.environ['EODAG_DEDL_AUTH_CREDENTIALS_PASSWORD'] = 'your_password'

# Initialize EODAG - authentication is automatic
dag = EODataAccessGateway()
dag.set_preferred_provider("dedl")

# Search and download - no additional auth needed
products = dag.search(productType="S2_MSI_L2A", start="2024-01-01")

Best for: STAC-focused workflows, token management control

Use destine-auth for robust token management:

import pystac_client
from destine_auth import AuthHandler

# Get authentication token
auth = AuthHandler(username="your_username", password="your_password")
token = auth.get_token()
headers = {'Authorization': f'Bearer {token}'}

# Create authenticated STAC client
catalog = pystac_client.Client.open(
    "https://hda.data.destination-earth.eu/stac/v2",
    headers=headers
)

# Search with authentication
search = catalog.search(collections=["EO.ESA.DAT.SENTINEL-2.MSI.L2A"])

Best for: Understanding the flow, debugging, non-Python environments

Important

Recommended: Use destine-auth or EODAG instead of implementing this manually. The OAuth2 flow is complex and these tools handle all edge cases and security considerations.

Complete OAuth2 authentication flow:

# Step 1: Get authorization code (browser-based)
AUTH_URL="https://auth.destine.eu/realms/desp/protocol/openid-connect/auth"
CLIENT_ID="dedl-hda"
REDIRECT_URI="https://hda.data.destination-earth.eu/stac"
SCOPE="openid profile"

# Navigate to this URL in browser:
echo "Visit: $AUTH_URL?client_id=$CLIENT_ID&redirect_uri=$REDIRECT_URI&response_type=code&scope=$SCOPE"

# Extract authorization code from redirect after login
read -p "Enter authorization code: " AUTH_CODE

# Step 2: Exchange code for DESP token
TOKEN_URL="https://auth.destine.eu/realms/desp/protocol/openid-connect/token"
DESP_TOKEN=$(curl -s -X POST "$TOKEN_URL" \
  -d "grant_type=authorization_code" \
  -d "client_id=$CLIENT_ID" \
  -d "redirect_uri=$REDIRECT_URI" \
  -d "code=$AUTH_CODE" | \
  jq -r '.access_token')

# Step 3: Exchange DESP token for DEDL token
DEDL_TOKEN=$(curl -s -X POST \
  "https://identity.data.destination-earth.eu/auth/realms/dedl/protocol/openid-connect/token" \
  -d "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
  -d "subject_token=$DESP_TOKEN" \
  -d "subject_issuer=desp-oidc" \
  -d "subject_token_type=urn:ietf:params:oauth:token-type:access_token" \
  -d "client_id=hda-public" \
  -d "audience=hda-public" | \
  jq -r '.access_token')

# Step 4: Use DEDL token for API calls
curl -H "Authorization: Bearer $DEDL_TOKEN" \
  "https://hda.data.destination-earth.eu/stac/v2/search?collections=EO.ESA.DAT.SENTINEL-2.MSI.L2A&limit=1"

Token Management

Token Lifecycle:

  • Access tokens: Valid for 10 hours

  • Refresh tokens: Can extend sessions without re-authentication

  • Automatic renewal: EODAG and destine-auth handle this automatically

Access Patterns

Discovery → Search → Access

  1. Discover services and collections (no authentication)

  2. Search for specific data items (authentication required)

  3. Download or stream data files (authentication required)

Edge Services Integration

  1. Discover available services (no authentication)

  2. Submit processing jobs (authentication required)

  3. Monitor job status and retrieve results (authentication required)

References

For more information about authentication and related tools:

Next Steps

Data Discovery

Start exploring available services and datasets

Data Access

Download data and work with ECMWF ordering workflows

FAQ & Troubleshooting

Troubleshooting authentication and quota issues