Secure use of API tokens

An API token is a key that grants full programmatic access to your account through the REST API. If it leaks, an attacker can do everything you can. The recommendations below reduce the risk that this happens to you.

Treat the token like a password

• Never paste a token into public repositories (GitHub, GitLab).
• Do not send a token via Discord, Slack or e-mail when debugging issues.
• Store the token in an environment variable or in a secret manager (HashiCorp Vault, AWS SSM Parameter Store, Doppler and similar).
• In a CI/CD pipeline (an automated build/deploy system) use the "masked secret" feature so that the token does not appear in logs in readable form.

Token rotation

In each of the following situations revoke the old token immediately and generate a new one:

• An employee who had access is leaving.
• In the dashboard you will see a Last used timestamp next to every token - if you see activity you did not expect, revoke the token immediately.
• At least once every 90 days as routine hygiene, even if nothing happened.

One token = one purpose

Do not put the same token into five different scripts. Create a separate token for each integration:

• epulzio_xxxxxxxxxxxxxxxx - only for deployments via GitHub Actions
• epulzio_xxxxxxxxxxxxxxxx - only for Terraform or Pulumi (infrastructure management tools)
• epulzio_xxxxxxxxxxxxxxxx - for a Grafana dashboard that pulls metrics

If one token leaks, you revoke only that specific one and the other integrations keep running.

Where to store the token safely

Token vs. signing secret for webhooks

For verifying incoming webhooks (the notifications we send to you) use a separate signing secret (HMAC signing secret), not the API token. They are two different things. Details can be found in Generating an API token.