Authentication

Public endpoints — probe and anchor lookups, measurements, locations, statistics — need no credentials at all. Anything tied to an account, and anything role-gated, needs an API key.

Create one at /account/api-keys; see API keys for issuing, scoping and rotating them. Key issuance requires a staff account.

Sending the key

The specification declares two security schemes, and authenticated endpoints accept either.

Header — use this one

curl -H "x-api-key: $ATLAS_API_KEY" \
  https://api.atlas.bluesapphiresoftware.net/probes/

The header keeps the secret out of URLs, and therefore out of server logs, browser history and referrer headers.

Query parameter

For tools that cannot set headers:

curl "https://api.atlas.bluesapphiresoftware.net/probes/?api-key=$ATLAS_API_KEY"

WARNING

Query-string credentials are logged by proxies and intermediaries as a matter of course. Treat any key you have sent this way as compromised once it has crossed a network you don't control, and rotate it.

Scopes

Every key carries read. A key additionally granted write may call state-changing endpoints. A read-only key calling a write endpoint is rejected — it is not a 404, so you can tell "not allowed" from "doesn't exist".

Roles still apply

An API key acts as the user it belongs to and does not escalate anything. A staff user's key reaches staff endpoints; it does not reach admin ones. If a request fails that you expected to work, check the role the endpoint needs before assuming the key is wrong — see Accounts and roles.

Sessions

The web app authenticates with a session cookie rather than an API key. That flow is an implementation detail of the app and is not part of the supported API surface — use a key for anything programmatic.

Keeping keys safe

• Store the secret in a secret manager, not in a repository or a shell history.
• Give each integration its own key, so one can be revoked without affecting the others.
• Check the last used timestamp and IP on the key page periodically.
• Set an expiry on keys issued for a specific, time-bounded job.