Service Token and Machine Credential Lifecycle Guide

Back to learning

API keys and service tokens are account-control surfaces. They may not belong to a human user, but they can still read data, call APIs, create load, change configuration, or keep access alive after a person leaves the team.

Treat them as non-human identities with a lifecycle, not as strings copied into a settings page.

Create with a purpose

Every key or token should have a clear job:

• Owner or team
• Workload or integration name
• Purpose
• Scope
• Environment
• Creation date
• Expiry or review date
• Rotation path
• Revocation path

If nobody can explain what a token is for, it is hard to decide whether it is safe. If one token is shared by many workloads, it is hard to rotate without breaking production.

Scope before distribution

Least privilege matters for machine credentials. A reporting integration should not have write access. A deployment token should not read customer data. A test token should not work in production.

Useful scopes include route, method, product area, account, environment, data class, and write capability. The exact model depends on the application, but the principle is the same: make the token useful enough for its job and no broader.

Display secrets safely

Raw secret material should usually be shown once, at creation time, then stored in a verifier-safe form. Persistent list and detail views should show a safe identifier, prefix, label, owner, scope, status, timestamps, and last-use information where available.

Do not put raw tokens in logs, email, analytics, screenshots, reports, or support tickets. If a user needs the value again, the safer pattern is to rotate or create a new token, not reveal the old one.

Review and rotate

Token review should not wait for an incident. Look for:

• Tokens with no owner
• Broad scopes
• No expiry or review date
• Long inactivity
• Use from unusual clients, routes, ASNs, or geographies
• Repeated failed authentication
• Use after employee, contractor, or vendor change
• Tokens created immediately after suspicious account activity

Rotation should be planned. A good rotation flow lets the owner create a replacement, move the workload, observe successful use, then revoke the old token. Emergency revocation still needs to be available when a token is exposed.

Monitor use, not just existence

A token inventory is only the start. Operators also need to see what tokens do: route use, volume, response codes, origin cost, errors, and policy actions. A low-volume token suddenly calling an export API is different from the same token making normal health checks.

Peakhour's API and rate-limiting controls can help attach request-path evidence to token decisions. The goal is to make machine access visible enough to narrow scope, rotate safely, and revoke quickly when the evidence changes.