Why service tokens
A service token lets agents access the platform with least privilege, without user accounts, and scoped to a single organization. Think of it as a per-environment key that you can rotate without touching user access.
What your team gets
- Fast agent onboarding without extra roles
- Separate tokens per environment (prod/stage) and team
- Smooth rotation: issue a new token and switch agents gradually
How the flow looks
- Admin creates a token in Settings → Service Tokens
- The token is shown once (format
vops_agent_...) - Agents connect with it and start reporting versions
Recommended roles and scoping
- Prod vs Stage: separate tokens to limit blast radius
- Per team (ops/sec/platform): easier to rotate and track ownership
- Per region: if latency or data boundaries matter
Rotation checklist (fast and safe)
- Issue a new token, update a few canary hosts
- Watch last_seen for a day, then roll out to the fleet
- Revoke the old token, note rotation in your runbook
Security tips
- Store the token in a secrets manager (Vault, SSM)
- Use different tokens for prod/stage
- Rotate on schedule and disable unused tokens
- Keep tokens out of git/CI logs
Common pitfalls to avoid
- Sharing one token across all environments
- Storing tokens in git/ansible vars without encryption
- Forgetting to disable tokens after experiments
Quick CLI example
# Configure agent with a fresh token
sudo versionops-agent config --backend=https://api.versionops.com --token=vops_agent_NEW
sudo systemctl restart versionops-agent
Helpful links
- Docs: Service Tokens
- App: Create a token
- Blog: Agent flow guide