Secure use of API tokens

3 min read

An API token gives full access to your account via the REST API. The following recommendations reduce the risk of compromise.

Token = like a password

• Never paste a token into public repositories (GitHub, GitLab)
• Do not paste a token into Discord / Slack / email when debugging
• Store the token in an environment variable or a secret manager (Vault, AWS SSM, Doppler)
• In CI/CD use a "masked secret" - logs must not contain plain text

Rotation

On each of these events, immediately revoke the old token and create a new one:

• An employee with access leaves
• You see an unexpected request in the API audit log
• At least once every 90 days as routine hygiene

One token = one purpose

Do not put the same token into 5 different scripts. Create:

• plz_ci_deploy - only for GitHub Actions deploy
• plz_terraform - only for Terraform / Pulumi
• plz_dashboards - for Grafana scraping

If one leaks, you only revoke that one - the other integrations are untouched.

Storage best practices

Token vs Webhook signing secret

For verifying incoming webhooks, use an HMAC signing secret, not the API token. Detail in Generating an API token.