Authentication

Two schemes are available. Each operation lists the one it accepts.

Bearer token (knoxApiToken)

For user-scoped access. Call POST /auth/login/ with HTTP Basic credentials to exchange a username and password for a token, then send the token on subsequent requests:

Authorization: Token <your-token>

API key (flashApiKey)

For server-to-server integrations, where the token expiry above would otherwise need handling. Keys are issued per organization. Send the key in its own header, not in Authorization:

X-Flash-Api-Key: fw_sk_live_<your-key>

Two kinds of key

The prefix tells you which one you are holding, and the two are not interchangeable.

A secret key reaches every endpoint your organization has bought. Treat it like a password: anything in client-side code or a public repository is compromised the moment it ships.

A publishable key is built to be seen. It reaches only the endpoints the widget needs, so publishing it is a non-event rather than a breach, which is why the widget builder asks for one and refuses a secret key. Requests with a secret key are also served no CORS headers, so a secret key simply will not work from a browser.

Checking a key is well-formed

Every key ends in a six-character checksum, so a truncated or mistyped key can be spotted before it is ever sent. A well-formed key is its prefix, 43 random characters, then those six.

Getting a key

API keys belong to an organization, not to a person, and both are set up by the FLASH Weather team. Get in touch to have yours created, tell us who should administer it.

Keys are issued by us. Your organization's administrators can rename, reveal and revoke them, so a leaked key can be killed immediately without waiting on us. A key is scoped to the organization that owns it and works for every endpoint that organization has access to.

Managing keys

A few things worth knowing before you build around them:

• The full key is shown once, when it is created. After that the list endpoint only ever returns the first characters, so store it somewhere durable at the moment you receive it.
• A lost key can be recovered without revoking it. One of your administrators can reveal the full value again, so a developer leaving does not mean re-deploying every integration that used their key. Every reveal is recorded against the key and emails all of your organization's administrators, naming the key and the reason given, whoever performed it, including us. The notification tells you a key was read; it never contains the key itself. If a reveal reaches you that nobody asked for, revoke the key and get in touch.
• A key may carry an expiry date, matching the term of your contract. Once it passes, the key stops returning data and every request using it fails with a message saying when it expired. Renewing extends the same key, so there is nothing to change in your integration, contact us before the date to arrange it. A key with no expiry date stays valid until it is explicitly revoked, which is what makes keys right for unattended integrations, and why leaking one matters more.
• Each key carries a label, unique within your organization. Use it to record where the key is deployed. "Which one is on the production ingest box?" is a question you want answered before revoking something.
• Ask for one key per integration rather than sharing a single key. Revoking a leaked key should not take down everything else you run.
• Usage is tracked per key: request counts and last-used timestamps, so an unused key is safe to revoke and a busy one tells you what it is doing.
• Keys carry their own rate limits, separate from the ones applied to user tokens. There are two ceilings: a per-minute one scoped to the key and the calling IP, and a larger hourly one covering every IP using that key. Parallel fan-out tends to hit the first; sustained daily volume hits the second. See Rate limits for the current figures.