---
name: avizmarlon/tokens-taxonomy
source: https://app.decimal.ai/s/avizmarlon-tokens-taxonomy@1/SKILL.md
source_sha256: 08e27128ff64
---

## 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.