Skip to content
satellitedata.net

Authentication

Available now

Section titled “Available now”

Lean v1 has one credential: an API key sent in the X-API-Key header.

Terminal window
curl -s "https://api.satellitedata.net/v1/search?collections=sentinel-2-l2a&limit=1" \
  -H "X-API-Key: $SDN_API_KEY"

Keys are API Gateway keys issued by the service owner, one per person. They do not have the sdn_ prefix of the planned self-service keys; examples elsewhere in these docs that show an sdn_... key are illustrations from the design, not real keys. The same keys work on api.satellitedata.net and on the older hosts stac. and tiles.satellitedata.net, and they share one usage plan (see Limits and quotas).

Which routes need a key

Section titled “Which routes need a key”
No key needed Key needed
GET /v1 GET /v1/collections/{collectionId}/items
GET /v1/conformance GET /v1/search, POST /v1/search
GET /v1/health GET .../items/{itemId}/preview.{format}
GET /v1/collections GET /v1/tiles/{presetId}/{tileMatrixSetId}/{z}/{x}/{y}.{format}
GET /v1/collections/{collectionId} POST /v1/process
GET /v1/collections/{collectionId}/items/{itemId} POST /v1/process/jobs, GET /v1/process/jobs/{jobId}
GET /v1/presets, GET /v1/presets/{presetId}
GET /v1/tiles/{presetId}/{tileMatrixSetId}/tilejson.json
GET /v1/openapi.json, GET /v1/schema

Routes that search or read pixels need a key. The full contract allows anonymous search under per-IP limits, but that depends on a web application firewall the lean setup does not have, so in lean v1 search needs a key.

Failures

Section titled “Failures”

A missing or unknown key on a route that needs one returns 401 with the problem code invalid-key and a WWW-Authenticate header. Lean v1 has no 403 case. This error comes from the gateway, so the request id is in the problem’s requestId rather than an X-Request-Id header.

The older hosts answer a missing or wrong key with a plain 403 Forbidden from API Gateway, not a problem document.

Keep keys out of URLs and pages

Section titled “Keep keys out of URLs and pages”
  • Send the key only in the header, never in a query string. URLs end up in logs, browser history and caches.
  • Keep it in an environment variable such as SDN_API_KEY, not in source code.
  • Anything in a web page’s code is readable by anyone who opens the page. Do not publish a page that contains a key. A personal tool that asks the user for their own key, as the web map does, is fine.

If a key leaks, ask the owner to replace it. A removed key stops working within a minute.

Coming later

Section titled “Coming later”

The full v1 contract adds three more credentials and self-service key management. None of these exist in lean v1.

Credential How it is sent Who it is for
API key from the dashboard X-API-Key: sdn_... Scripts, notebooks, servers
OAuth 2.0 client-credentials token Authorization: Bearer <JWT> from POST /oauth/token Sentinel Hub style clients
Website session Authorization: Bearer <access token> The website’s dashboard and explorer
Guest token Authorization: Bearer <JWT> Signed-out visitors to the website: one hour, 100 units, tiles and previews only

Planned details:

  • Self-service keys. Sign up, verify your email, then create keys from the dashboard (POST /v1/keys). A key is sdn_ followed by 40 letters and digits, shown once. A free account holds at most two active keys. Keys have scopes: data (the default) and account (adds key management).
  • OAuth 2.0. POST /oauth/token with the client-credentials grant returns a one-hour token. Each key has a paired client id, and the key is the client secret. Reuse a token until it expires; the endpoint allows 10 tokens per client per minute.
  • Anonymous search under per-IP limits, and anonymous tiles and previews served from the CDN cache.
  • More failure codes: email-unverified, insufficient-scope, key-suspended and invalid-client.

See the full contract for the planned routes.