Getting started

Authentication

API keys, the three ways to send them, anonymous access, and how quotas attach to your account.

What needs a key

Surface Anonymous With API key
STAC catalog (/collections, /search, …) ✓ 30 req/min per IP Higher per-plan limits
Elevation API (/v1/elevation/*) ✗ 401 ✓
COG downloads (/dl/...) ✗ 401 Paid plans only
/v1/health ✓ ✓

Keys are free: sign up, then create one under Dashboard → API keys. The full key is displayed once at creation.

Sending the key

Three equivalent forms, in order of preference:

curl "https://api.darly.io/v1/elevation/point?lat=45.51&lon=-73.56" \
  -H "X-API-Key: $DARLY_API_KEY"

Prefer the headers. The gateway strips api_key from the query string before forwarding requests upstream, but a key sent in a URL can still land in intermediary and access logs along the way.

Keys, users, and quotas

  • Quotas are per account, not per key. All keys you create draw from the same monthly budgets and per-minute limits. Create as many keys as you want to separate environments or teammates' tools — revoking one never affects the others.
  • Revoke keys anytime in Dashboard → API keys; revocation is immediate.
  • Your plan's limits are listed in rate limits & quotas.

Auth errors

Case Response
Elevation call without authentication 401 {"detail": "Authentication is required for the elevation API"}
Download without authentication 401 {"detail": "Authentication is required to download assets"}
Invalid or revoked key Treated as anonymous: STAC keeps working at the anonymous limit; elevation calls get the 401s above
Plan doesn't include the endpoint 403 {"detail": "The current plan does not include this endpoint"}
Plan doesn't include downloads 403 {"detail": "The current plan does not include downloads"}

A silent fallback to anonymous access on a bad key can be surprising: if STAC calls work but elevation calls return 401, check the key value first.