Skip to content

API tokens

An API token lets a script or app manage your webhooks through the Webhooks API: create, list, edit, delete and test them. It does the same job as the Webhooks page in your account, from code.

A token can only manage webhooks. It can’t change your account or create other tokens. But because it can add a webhook, anyone who holds it can have your units’ alerts sent to their own server, so keep it as safe as a password.

  1. Sign in at my.gridwatchdog.com/account.
  2. Under Integrations, choose API tokens.
  3. Optionally, give the token a name so you remember what it’s for, such as the script that uses it.
  4. Under Expires, choose when the token stops working. Unless you change it, a token expires 365 days after you create it. You can also pick a shorter lifetime, or never.
  5. Choose Create token.

The token is shown once, on the page that opens. Copy it now and keep it somewhere safe, such as a password manager or your script’s secret settings. We store only a hashed copy, so we can’t show it to you again. If you lose it, revoke it and create a new one.

Every token starts with gwk_.

Tokens can only be created while you’re signed in with a browser. A token can’t be used to create another token. We email you whenever a token is created.

Your token list shows when each token expires. An expired token stops working exactly like a revoked one, so create a new one before then.

Send the token in the Authorization header of every request:

Authorization: Bearer gwk_your_token_here

For example, to list your webhooks:

Terminal window
curl -H "Authorization: Bearer gwk_your_token_here" \
https://my.gridwatchdog.com/account/webhooks

The Webhooks API reference lists every endpoint.

Choose Rotate… next to an active token, then Rotate this token. The old token stops working immediately, and a new one is shown once, just as when you create a token. Update your script to use the new token.

The new token keeps the old one’s expiry setting: if the old token never expired, neither does the new one; otherwise the new token gets the same lifetime again, counted from the rotation. Rotating counts against the limits.

Choose Revoke… next to an active token. The page that opens lists every webhook the token created or last changed; choose Revoke this token to confirm. The token stops working immediately: a request that uses it gets a 401 response with { "error": "invalid_token" }. A revoked token can’t be switched back on, so create a new one if you need it again.

Revoking a token does not switch off the webhooks it created or changed. The list stays on the page so you can review each one.

If none of your units is registered to your address any more (it was removed, set up again under a different address, or moved to a new address), that address’s tokens are revoked and its webhooks switched off automatically.

  • You can have up to 10 active tokens at a time.
  • You can create up to 10 new tokens per 60 minutes. Rotating a token counts as creating one.

If you reach either limit, creating or rotating a token shows an error instead of a token, and a rotation that was refused leaves the old token working. Revoke tokens you no longer use, or wait and try again later.

We email you whenever a token is created, and whenever a token adds a webhook or changes a webhook’s URL. Each email links straight to that token’s revoke page.

If a token might have leaked:

  1. On the API tokens page, choose Revoke… next to it and confirm. The page then lists every webhook that token created or last changed. Revoking doesn’t switch those webhooks off.
  2. Disable any webhook in that list you don’t recognise (or delete it on the Webhooks page), and check that every webhook you keep still points at your own URL.
  3. Choose New signing secret on each generic webhook, and give your endpoint the new secret. Each webhook shows when its secret was last rotated, so a rotation you didn’t make stands out.

Use a separate token for each script or service, so you can revoke one without breaking the others.