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:
- 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.
- 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.
- Fast revocation velocity. A CI token leaks → revoke only that one, ops continues unaffected. Without separation, any leak breaks everything.
- Zero cost. Every major platform supports multiple tokens per account; creating one takes 30 seconds.
- 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.
1---2name: tokens-taxonomy3description: API key and token strategy — one token per purpose, least-privilege separation, distinct scopes for CI/automation vs. manual operations vs. read-only access. Use when designing token/credential architecture, rotating credentials, setting up API access for multi-purpose systems, or implementing least-privilege token management.4---56## Token Taxonomy — One Token Per Purpose — Hard Rule78**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.910**Why this matters:**11121. **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.132. **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.143. **Fast revocation velocity.** A CI token leaks → revoke only that one, ops continues unaffected. Without separation, any leak breaks everything.154. **Zero cost.** Every major platform supports multiple tokens per account; creating one takes 30 seconds.165. **Industry-standard IAM pattern.** AWS IAM, GCP service accounts, GitHub Apps, and enterprise OAuth scopes all follow this structure.1718## How to Apply1920| Situation | Decision |21|---|---|22| Platform with one caller only (one manual script) | 1 token with minimal scope. Acceptable. |23| Platform with 2+ different callers (CI + agent + scheduled job + manual ops) | **Separate by caller category.** Minimum 2: one for CI/automation + one for ops. |24| One "universal" token used everywhere | **Anti-pattern.** Refactor. |25| 10+ fragmented tokens (one per workflow) | **Anti-pattern.** Consolidate into 2–3 categories. |2627## Standard Token Categories2829Adjust these for your platform, but the pattern is universal:3031- `<service>-ci-bot` — deploy, trigger, release actions only. Deployed to CI/automation systems (GitHub Actions, GitLab CI, scheduled tasks, etc.).32- `<service>-ops-bot` — full read/write for operational tasks. Stored securely for manual use, agent-driven operations, sysadmin scripts.33- `<service>-readonly-bot` — read-only access. For dashboards, monitoring, audit logs. Optional; skip if not needed.3435## Documentation Requirements3637Every project using multiple tokens **must** maintain an **API inventory** (suggested: `docs/api-inventory.md` or equivalent) listing:3839- Logical token name (e.g., `github-ci-bot`, `slack-ops-bot`)40- Scope and permissions41- Storage location (vault item ID, environment variable name, file path)42- Which systems/scripts consume it43- Last rotation date and rotation cadence4445This inventory is your audit trail and your incident-response checklist.4647## Anti-Patterns (Prohibited)4849- **One broad token used by all scripts** → reorganize into category-based tokens.50- **Generic names** (`default`, `test`, `bot1`) → rename to purpose-descriptive names.51- **Undocumented tokens** → register in the API inventory before using.52- **Token value committed to version control** → revoke immediately, create replacement, log the incident.53- **Fragmented tokens without clear category** → consolidate.54- **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.).5556## Storage Recommendations5758- **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.59- **Ops/agent tokens** — store in a secure credential vault (HashiCorp Vault, 1Password, Bitwarden, AWS Secrets Manager, etc.) where the agent can retrieve them programmatically.60- **Read-only tokens** — store wherever read-only is sufficient; can be slightly less restricted than ops tokens.61- **Local development** — use `.env` files (with `.env` in `.gitignore`) or local credential managers. Never commit token values.6263## Applies To6465All 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.6667**Use this across all AI agents and tooling**, regardless of platform or framework.
avizmarlon