Device Tokens#

Self Hosted Cloud Hosted

Every gravity sensor you connect to BrewGraph — an iSpindel, a Gravitymon, or a Tilt through TiltBridge — is given its own device token the moment you register it. The token is what lets that specific piece of hardware send readings to your account.

Why the token exists#

Your BrewGraph account can have devices belonging to you and only you. When a reading arrives, BrewGraph has to answer two questions: which account does this belong to and which device sent it. The token answers both. It travels along with every reading the device sends, and it’s the only thing tying that hardware to your batches, taps, and vessels.

PressureMon and KegMon are coming soon to Cloud Hosted and are not available in the beta. On Self Hosted, a KegMon token identifies a tap rather than a device; the rest of this page applies to device tokens.

Nobody else can see your token, and BrewGraph itself can’t show it back to you after the moment it’s created — more on that below.

That secrecy is only as good as what you do with it afterwards: don’t publish a token in screenshots, issue reports, or a public repository. A firmware config file that leaked one is itself a reason to rotate it — see “When to rotate a token” below.

Self Hosted matching by chipId#

Self Hosted

On a Self Hosted installation, BrewGraph can also match incoming readings by the device’s chipId. This is the standard device identifier used across the project, and can make local device setup simpler.

That matching method is deliberately not available in the hosted SaaS service. A chipId is not guaranteed to be globally unique, so a collision could cause a reading to be associated with the wrong account or device. Hosted BrewGraph therefore uses the per-device token to identify every incoming reading safely.

You’ll see the token once#

When you add a new device, BrewGraph generates the token and shows it to you exactly once, on the device screen. Copy it into your device’s firmware configuration right then. After that screen closes, BrewGraph doesn’t store the token in a form it can display again — it only keeps a one-way, non-reversible version of it, enough to verify future readings but not enough to recover the original value.

This isn’t a bug or an oversight — it’s the same reason your BrewGraph account password isn’t stored in plain text either. If you didn’t write the token down and the device is already running, you don’t need to do anything: it keeps working. The token only becomes a problem if you need to re-enter it somewhere, and it’s gone.

What happens if you lose or rotate a token#

If you did not save the token when it was created, check the device’s firmware configuration first. Most devices store it there in clear text, so you can retrieve the existing token without changing anything in BrewGraph.

If you need to replace it — for example, after a firmware re-flash or when setting up a replacement device — generate a new token from the device’s settings in BrewGraph. This is called rotating the token.

The important consequence: generating a new token immediately invalidates the old one. Any readings the physical sensor sends using the old token will be rejected from that moment on. The device itself doesn’t know its token changed — you have to open the sensor’s own configuration (its web interface, its firmware settings file, whatever your hardware exposes) and paste in the new token, the same way you did during initial setup.

In practice, that means:

  • Rotating a token is a two-step action: generate the new one in BrewGraph, then go update the physical device. Doing only the first half leaves the sensor unable to report until you finish the second half.

  • If a sensor suddenly stops reporting, a mismatched or rotated token is one of the most common causes — check the device’s configuration against what BrewGraph currently has on file.

  • Rotating a token doesn’t delete any history. All the readings the device already sent stay attached to your batches and vessels; only future readings need the new token to be accepted.

When to rotate a token#

Rotate a device’s token if you suspect it’s been exposed (for example, a firmware config file was shared or committed somewhere public), or if you’re repurposing a sensor and want a clean break from its ingest history going forward. Routine use doesn’t require rotating tokens on any kind of schedule.

When a device’s data is not arriving#

Cloud Hosted

Two tools in Settings help you find out why.

Ingestion log shows the 15 newest requests from your devices that BrewGraph turned away, each with the reason, the device, where it came from, its IP address, and some detail. Download saves all of them as a JSON file. Requests that use a token BrewGraph does not recognise are not shown, so a mistyped or old token will not appear here; check the token on the device first. Readings refused because they arrived before the account’s reporting interval are also shown in this log.

Payload capture under Settings shows what a device sends, which is useful when setting up a device type BrewGraph does not support yet. Send a POST to https://ingest.brewgraph.com/api/ingest/test; if the device cannot send a token in its request, use https://ingest.brewgraph.com/api/ingest/test/<token> with the token as the last part of the URL. The token can also be sent in a request header, body, or query parameter. The 20 newest captures are kept for 7 days, and the token is masked in the stored request.