avizmarlon/tokens-taxonomy

Token Taxonomy — One Token Per Purpose — Hard Rule

Principle: Each API key or authentication token should have a single, well-defined purpose with a descriptive name. This is not binary ("broad vs. narrow") — it's 2–3 tokens with clearly demarcated scopes, one per category of use.

Why this matters:

1. Real least privilege, not theater. A broad token in a CI workflow that leaks via logs compromises everything. A narrow token leaks only that specific purpose.
2. Asymmetric blast radius. Tokens in CI/automation (GitHub Actions, scheduled workers, third-party scripts) have high leak surface. Tokens in ops (manual scripts, agent-driven tasks) live in local env vars or secure vaults — smaller surface.
3. Fast revocation velocity. A CI token leaks → revoke only that one, ops continues unaffected. Without separation, any leak breaks everything.
4. Zero cost. Every major platform supports multiple tokens per account; creating one takes 30 seconds.
5. Industry-standard IAM pattern. AWS IAM, GCP service accounts, GitHub Apps, and enterprise OAuth scopes all follow this structure.

How to Apply

| Situation | Decision | |---|---| | Platform with one caller only (one manual script) | 1 token with minimal scope. Acceptable. | | Platform with 2+ different callers (CI + agent + scheduled job + manual ops) | Separate by caller category. Minimum 2: one for CI/automation + one for ops. | | One "universal" token used everywhere | Anti-pattern. Refactor. | | 10+ fragmented tokens (one per workflow) | Anti-pattern. Consolidate into 2–3 categories. |

Standard Token Categories

Adjust these for your platform, but the pattern is universal:

• <service>-ci-bot — deploy, trigger, release actions only. Deployed to CI/automation systems (GitHub Actions, GitLab CI, scheduled tasks, etc.).
• <service>-ops-bot — full read/write for operational tasks. Stored securely for manual use, agent-driven operations, sysadmin scripts.
• <service>-readonly-bot — read-only access. For dashboards, monitoring, audit logs. Optional; skip if not needed.

Documentation Requirements

Every project using multiple tokens must maintain an API inventory (suggested: docs/api-inventory.md or equivalent) listing:

• Logical token name (e.g., github-ci-bot, slack-ops-bot)
• Scope and permissions
• Storage location (vault item ID, environment variable name, file path)
• Which systems/scripts consume it
• Last rotation date and rotation cadence

This inventory is your audit trail and your incident-response checklist.

Anti-Patterns (Prohibited)

• One broad token used by all scripts → reorganize into category-based tokens.
• Generic names (default, test, bot1) → rename to purpose-descriptive names.
• Undocumented tokens → register in the API inventory before using.
• Token value committed to version control → revoke immediately, create replacement, log the incident.
• Fragmented tokens without clear category → consolidate.
• Storing all tokens the same way (all in env vars, all in one vault, etc.) → use appropriate storage per risk level (CI tokens more isolated, ops tokens in vault for agent access, etc.).

Storage Recommendations

• CI/automation tokens — store in native platform secrets (GitHub Secrets, GitLab CI/CD Variables, Cirrus CI secrets, etc.). These are ephemeral and not accessible outside the pipeline.
• Ops/agent tokens — store in a secure credential vault (HashiCorp Vault, 1Password, Bitwarden, AWS Secrets Manager, etc.) where the agent can retrieve them programmatically.
• Read-only tokens — store wherever read-only is sufficient; can be slightly less restricted than ops tokens.
• Local development — use .env files (with .env in .gitignore) or local credential managers. Never commit token values.

Applies To

All platforms with API authentication: cloud providers (AWS, GCP, Azure), SaaS platforms (GitHub, GitLab, Slack, Discord), infrastructure tools (Terraform, Kubernetes), deployment systems, monitoring/observability platforms, and any third-party integrations.

Use this across all AI agents and tooling, regardless of platform or framework.