Authentication

Every request needs an API key. Keys are issued in the dashboard under Settings › API, and belong to your account rather than to you: every key on the account counts against the account's API plan, and any calls beyond it are billed to the account's card.

Sending the key

Send it in a header, either form:

# Preferred
curl -H "Authorization: Bearer $AOT_API_KEY" "https://api.aussieoutagetracker.com.au/v1/networks"
 
# Also accepted, for clients that cannot set Authorization
curl -H "X-API-Key: $AOT_API_KEY" "https://api.aussieoutagetracker.com.au/v1/networks"

Never put a key in a URL

A key in a query string ends up in proxy logs, browser history and Referer headers. The API refuses a request carrying api_key, key or token in its query string with a 401, even when the key itself is valid, rather than accept it once and teach the habit.

The key itself

aot_live_ then 32 characters. A live key, issued on an account with the API plan.
aot_test_ then 32 characters. A test key, issued while billing runs in its test mode. It works the same way; the prefix is there so a key copied out of a test environment announces itself.
Shown once. The dashboard shows the whole key only when it is created. We store a one-way hash of it, so a lost key cannot be recovered — revoke it and create another. The dashboard lists each key by its first few characters (aot_live_3fK9…) so you can tell them apart.
Several keys per account. Use one per integration and environment, so a leak is easy to find and revoking one key does not break the others. The dashboard says when the account is at its limit.

Revoking a key

Revoke a key in Settings › API. It stops working within a minute: the API caches each key's standing for up to sixty seconds so that a metered call does not pay for three database lookups. Plan rotations with that minute in mind — create the new key, deploy it, then revoke the old one.

Who can use the API

A key works while its account has the API plan — started in Settings › API, its payment confirmed, and billing not past due — or the account is on an Enterprise agreement and has the API by arrangement. A cancelled plan keeps working to the end of the month it paid for. See Billing and usage.

When a key is refused

Status	`error.code`	Why
`401`	`unauthorized`	No key was sent, the key is not valid or has been revoked, or the key was put in the URL.
`402`	`payment_required`	The key is valid, but its account has no API plan, its plan's first payment is still being confirmed, or billing is past due. The message says which.
`403`	`forbidden`	The account is suspended, or its API access has been switched off.

A 401 also carries a WWW-Authenticate: Bearer realm="aot" header, with error="invalid_token" when a key was sent but not recognised.

401GET /v1/outages

{
  "error": {
    "code": "unauthorized",
    "message": "Missing API key. Send Authorization: Bearer aot_…"
  }
}

None of these is billed. See Errors for every code.