Vault token taxonomy — function mapping, tag system, and provisioning template

Status: Phase 2 in progress — Cloudflare rename complete (#754); other vendors pending Owner: operator / sre-agent Last updated: 2026-05-01 UTC Tracking: #754 (CF token rename), refs #81 (Epic: SDLC, Tooling, and Security Hardening)

Related issues: #402 (secrets-store org review), #596 (env coverage audit), #747 (WAF token gap), #253 (rotation pipelines)

Background

As of 2026-04-30 the vault at vault.raxx.app has 20+ credentials across 8 vendors. Several pain points have emerged:

• Token names do not communicate scope — CLOUDFLARE_RAXX_AUTOMATION_API_TOKEN was tested against multiple CF endpoints before an SRE agent confirmed it was missing WAF Edit scope (see #747).
• Multiple tokens per vendor with overlapping-sounding names force reliance on operator memory as the source of truth.
• No canonical template for provisioning a new token — what scopes to grant, where to store it, what to call it.
• Environment coverage (prod vs. staging vs. dev) and rotation cadence are inconsistently captured.

This document locks in a taxonomy that solves all four.

Section 1 — Naming convention

Chosen pattern: <VENDOR>_<FUNCTION>_<SCOPE>

<VENDOR>   two-to-four-letter vendor code (CF, HK, PM, AWS, ANT, GH, STR, ALP, INF, SL)
<FUNCTION> verb-noun describing what the token does (DNS_EDIT, WAF_EDIT, PAGES_DEPLOY, etc.)
<SCOPE>    optional — only present when a vendor issues the same function-type for multiple targets

Examples:

Why this pattern over deeper path nesting

Two alternatives were evaluated:

Option A — deeper path, shorter names:

/MooseQuest/cloudflare/dns-edit/RAXX_APP_TOKEN
/MooseQuest/cloudflare/waf-edit/RAXX_APP_TOKEN

Advantage: path carries the metadata, secret name is just TOKEN. Problem: Infisical's feedback_vault_folder_must_exist.md constraint means every leaf folder must be pre-created. Four Cloudflare function-types = four folders to manage. More surface area for folder-creation 404s. Path segments do not appear in audit log snippets — you need the full path context to understand the audit trail.

Option B — vendor flat with fully-qualified name (chosen):

/MooseQuest/cloudflare/CF_DNS_EDIT_RAXX_APP
/MooseQuest/cloudflare/CF_WAF_EDIT_RAXX_APP

Advantage: the secret name is self-describing. Audit log entries, vault list output, Slack alerts, and console UI all show the key name without needing path context. One folder per vendor (already created). Consumer code reads CF_DNS_EDIT_RAXX_APP and anyone reading the code knows the function and scope without looking up a mapping.

Decision: Option B. One folder per vendor, self-describing key names. The <VENDOR>_<FUNCTION>_<SCOPE> pattern carries enough context in the name alone.

Scope qualifier rules

• Omit scope when there is exactly one token for that function (HK_PLATFORM_FULL — Heroku has one account).
• Include zone/app scope when the vendor may issue separate tokens per zone or deployment (CF_DNS_EDIT_RAXX_APP vs. CF_DNS_EDIT_GETRAXX_COM).
• Use _FULL suffix when the token has unrestricted (admin) access to its function domain — signals to provisioners that least-privilege is not achieved and a scoped replacement should be prioritized.

Companion secrets (no change from #402 decision)

Companion metadata fields use double-underscore suffix convention:

• CF_DNS_EDIT_RAXX_APP__EXPIRES_AT — ISO-8601 UTC expiry
• CF_DNS_EDIT_RAXX_APP__SCOPES — space-separated vendor scope names (for quick audit without hitting vendor API)
• CF_ACCESS_SVC_VAULT__CLIENT_ID — paired ID for CF Access service tokens

Section 2 — Tagging strategy

Tags are applied in Infisical on each secret. Four dimensions — no more.

Tag set

function: — What the token does

sensitivity: — Production risk if leaked

consumer: — Which system uses the token

Multiple consumer tags are allowed on one secret (e.g., a DNS token used by both Terraform and CI).

rotation: — Cadence

Tag discipline rules

1. Every secret gets exactly one tag from each dimension.
2. If a token is used by multiple consumers, pick the primary one — the one that would be paged if the token expired.
3. Tags are not a substitute for the companion __SCOPES field. Tags say what the token broadly does; __SCOPES documents the exact vendor permission strings.
4. sensitivity:critical requires a paired ops review in the provisioning PR — no solo provisioning.

Section 3 — Environment usage

Infisical environments: prod, staging, dev.

Guiding rules

Rule 1 — Env-specific credentials live in both prod and staging with different values. If the vendor isolates accounts or projects by environment (separate Heroku apps, separate Alpaca paper accounts), the token must have env-specific values. Both envs are populated, values differ.

Rule 2 — Account-wide tokens that serve all environments live in prod only, consumed by both. A Cloudflare account token (DNS, WAF, CF Access) controls the whole account regardless of whether a staging or prod deploy calls it. There is one Cloudflare account. Store in prod; consumers in staging read from prod path explicitly. Do NOT duplicate with an identical value into staging — duplicates drift and cause "which env's value is real?" confusion.

Rule 3 — Dev environment is populated only for tokens that have a dev-mode analog. Most secrets do not have a dev analog (there is no "dev CF account"). Dev env in Infisical stays sparse. Local dev uses .env files (gitignored). Infisical dev is used only for tokens where the vendor offers sandbox/test mode keys (e.g., Stripe test-mode key = dev env).

Classification table

Section 4 — Token-to-function index

All tokens currently known in vault or referenced in rotation matrix / issues, grouped by vendor.

Cloudflare — User API Tokens (/MooseQuest/cloudflare/)

Note: CLOUDFLARE_RAXX_AUTOMATION_API_TOKEN and CLOUDFLARE_PAGES_DEPLOY_TOKEN may overlap in scope — Kristerpher should confirm whether these are the same token stored under two names or two distinct tokens. If the same, one should be deprecated after migration. See Section 7 open question.

Cloudflare — Access Service Tokens (/MooseQuest/cloudflare/)

Heroku (/MooseQuest/heroku/)

Note: Two Heroku entries in the rotation matrix (HEROKU_API_KEY and HEROKU_PLATFORM_API_TOKEN) likely refer to the same logical credential. Confirm and deduplicate; see Section 7.

Postmark (/MooseQuest/postmark/)

AWS (/MooseQuest/aws/)

AWS key pairs are stored as companion secrets: AWS_INFISICAL_BOOTSTRAP__ACCESS_KEY_ID and AWS_INFISICAL_BOOTSTRAP__SECRET_ACCESS_KEY. The base key name is the logical credential; suffixes are the two components. This avoids a _KEY_ID / _SECRET_KEY naming ambiguity.

Anthropic (/MooseQuest/anthropic/)

GitHub (/MooseQuest/github/)

GitHub Apps — bot identities (/MooseQuest/raxx-dev-bot/, /MooseQuest/raxx-ops-bot/, /MooseQuest/raxx-pm-bot/)

Each bot path holds three companion secrets (APP_ID, INSTALLATION_ID, PRIVATE_KEY_PEM). Under the new taxonomy these are grouped as one logical credential per bot:

Bot key paths retain their existing path structure (/MooseQuest/raxx-*-bot/) because mint_github_token.py hard-codes these paths. Rename only after updating the script.

Stripe (/MooseQuest/stripe/)

Alpaca (/MooseQuest/alpaca/)

Alpaca key pairs use the __KEY_ID / __SECRET_KEY companion pattern: ALP_PAPER_TRADING__KEY_ID and ALP_PAPER_TRADING__SECRET_KEY.

Infisical (/MooseQuest/infisical/)

Slack (/MooseQuest/slack/)

DreamHost / Oracle Dyn (legacy)

Section 5 — Provisioning template

When a new token needs to be created, walk these steps in order. Steps 1-4 are one-time per token; step 5 is done whenever a new consumer is wired up.

Step 1 — Assign a name and path

1. Choose the vendor code from the table in Section 1.
2. Choose a function keyword that matches the permission being granted (match an existing function: tag if possible; if new, propose to this doc as a PR first).
3. Add a scope suffix if the vendor issues per-zone or per-app tokens.
4. Full proposed name: <VENDOR>_<FUNCTION>[_<SCOPE>]
5. Path: /MooseQuest/<vendor-lowercase>/ — verify the folder exists in Infisical before writing. If not, create via POST /api/v1/folders (per feedback_vault_folder_must_exist.md).

Step 2 — Provision the token at the vendor

Step 3 — Store in vault

# 1. Verify folder exists (or create it)
curl -s -H "Authorization: Bearer $INFISICAL_TOKEN" \
     -H "CF-Access-Client-Id: $CF_ACCESS_CLIENT_ID" \
     -H "CF-Access-Client-Secret: $CF_ACCESS_CLIENT_SECRET" \
     "https://vault.raxx.app/api/v1/folders?workspaceId=$PROJECT_ID&environment=prod&path=/MooseQuest/<vendor>"

# 2. Create the secret
#    (Use Infisical UI for first provisioning; use rotation pipeline for subsequent rotations)

# 3. Create companion secrets (always):
#    <NAME>__EXPIRES_AT  = ISO-8601 UTC expiry or "non-expiring"
#    <NAME>__SCOPES      = space-separated vendor scope strings

Step 4 — Apply tags

In Infisical UI → select secret → Tags → add the four required tags:

function:<tag>
sensitivity:<level>
consumer:<primary-consumer>
rotation:<cadence>

If the secret is sensitivity:critical, add a comment in the provisioning PR describing who was notified.

Step 5 — Register the consumer reference

For each consumer type, add the new key name to the canonical reference location:

Step 5 is required. No orphan tokens — every token in vault must have at least one documented consumer reference.

Step 6 — Add to rotation matrix

Open docs/ops/runbooks/rotation/INDEX.md and add a row:

| <NEW_NAME> | <Vendor> | operator-assisted | <sop-link> | <cadence> | TBD | TBD |

If no vendor-specific SOP exists yet, create one under docs/ops/runbooks/rotation/ before filing the provisioning PR.

Section 6 — Migration plan

Phase 0 — Design complete (this document)

No token is renamed or moved. Existing consumers are unaffected. The taxonomy doc is the reference for all net-new tokens provisioned from this point forward.

Phase 1 — New tokens follow the taxonomy (immediate, no migration needed)

Starting with CF_WAF_EDIT_RAXX_APP (#747) — the first token to be provisioned after this doc exists — all new tokens use the new naming and tagging convention.

Phase 2 — Parallel rename (one PR per vendor)

For each vendor:

1. Add the new-taxonomy name as a new secret in vault pointing to the same value (do not delete the old name yet).
2. Update all consumer references in one PR: rename the env var in CI workflows, Terraform, vault.py, and runbooks.
3. Smoke-test in staging: verify the consumer works with the new name.
4. Merge the PR.
5. After the PR is merged and the next deploy succeeds, delete the old-taxonomy name from vault.

Vendor order (suggested — highest impact first):

1. Cloudflare — most tokens, most ambiguity, most consumers (CI + Terraform + agent). File as one PR per CF function (DNS, WAF, Pages, Access).
2. Heroku — deduplicate the two platform-key entries.
3. AWS — rename to companion-secret pattern.
4. Postmark — two tokens, low consumer count.
5. Alpaca — rename to companion-secret pattern.
6. Anthropic, GitHub, Slack, Stripe — single tokens, low friction.
7. Infisical, bot paths — last, because mint_github_token.py must be updated simultaneously.

Phase 3 — Rotation matrix updated

After all vendor renames complete, update docs/ops/runbooks/rotation/INDEX.md to use new names. Old entries marked [archived].

Rotation safety protocol during parallel rename

During the parallel rename window (old + new names both exist):

• Rotation pipeline rotates OLD name only until the consumer PR lands.
• After consumer PR merges, rotation pipeline switches to NEW name.
• Old name is revoked at vendor dashboard the same day it is deleted from vault.
• Never let both names be valid simultaneously for longer than one deploy cycle.

Section 7 — Open questions for Kristerpher

Q1 — Are CLOUDFLARE_RAXX_AUTOMATION_API_TOKEN and CLOUDFLARE_PAGES_DEPLOY_TOKEN the same physical token?

The rotation matrix and the memory reference (reference_cloudflare_tokens.md) name both tokens. If they are the same token stored under two names, one name should be deprecated immediately after the canonical new name is provisioned. If they are distinct (different scopes), the function mapping needs to reflect that. The taxonomy proposes CF_PAGES_DEPLOY for the Pages-deploy function — confirm whether the automation token also has Pages scope or whether it is truly distinct.

Q2 — Rotation cadence enforcement: Infisical expiration or documented only?

Infisical supports setting an expiration date on a secret (it will be flagged as expired in the UI and rotation alerts fire). The taxonomy documents cadences, but does not mandate using Infisical's expiration field. Recommendation: use the __EXPIRES_AT companion secret for auditable tracking and let the console rotation UI read it (#253, #254). Infisical's native expiration is a belt-and-suspenders option. Kristerpher to decide whether to enable native expiration (no implementation work — just a UI toggle per secret) or rely solely on the rotation pipeline's scheduling.

Q3 — DNS edit: one token for both raxx.app and getraxx.com, or two?

Option A — one token with both zones in scope: simpler rotation, wider blast radius if leaked. Option B — two tokens, one per zone: least-privilege, higher provisioning overhead. The taxonomy proposes Option B (CF_DNS_EDIT_RAXX_APP and CF_DNS_EDIT_GETRAXX_COM) as the default. If Kristerpher prefers Option A for operational simplicity, the scope suffix becomes CF_DNS_EDIT_ACCOUNT (or just CF_DNS_EDIT) and the __SCOPES companion documents both zones. Either is valid — but the decision should be made before any migration PR is filed.

Q4 — Are there any tokens not in this index?

This index is built from the rotation matrix (INDEX.md), the vault README, issues #402/#596/#747, and the memory notes. If any tokens exist in vault that are not listed here — particularly any remaining CLOUDFLAREROLLED, legacy bootstrap tokens, or per-agent access tokens — they should be audited against this taxonomy before the Phase 2 migration starts. Kristerpher's live read of vault contents (using the CF Access service token and Infisical list API) would surface any gaps.

Q5 — Should ALP_LIVE_TRADING ever exist in vault at all pre-launch?

The live trading keys control real money. Before Raxx has live-trading users, these keys belong to the operator's personal Alpaca account. The taxonomy includes them for completeness, but the provisioning decision — whether to store live keys in vault now or defer until first live user — is Kristerpher's call. Recommendation: store in vault under sensitivity:critical with consumer:raptor and rotation:60d even pre-launch, so the rotation pipeline can enforce cadence on the keys that matter most.

Appendix A — Vendor code reference

Appendix B — Checklist for net-new token provisioning PR

[ ] Name follows <VENDOR>_<FUNCTION>[_<SCOPE>] pattern
[ ] Path folder verified to exist (or created via POST /api/v1/folders first)
[ ] Secret created in correct Infisical environment(s) per Section 3 table
[ ] __EXPIRES_AT companion secret set
[ ] __SCOPES companion secret set (exact vendor permission strings)
[ ] All four tag dimensions applied (function, sensitivity, consumer, rotation)
[ ] If sensitivity:critical — ops review noted in PR description
[ ] Consumer reference added (CI workflow / Terraform / vault.py / runbook)
[ ] Row added to docs/ops/runbooks/rotation/INDEX.md
[ ] Vendor-specific SOP exists at docs/ops/runbooks/rotation/<vendor>.md