Task Plan: Operator Stream

Author: Miguel Pinilla Date: 2026-05-07 Status: Planning

Summary

Author the operator-facing runbook for the Account Holder persona. The runbook walks through Amazon Creators API registration, Application creation, credential generation, the four 1Password vault entries that engineering needs, and the hand-off back to engineering for the infrastructure deploy.

This stream is independent of the other three streams at the code level. It contributes a documentation deliverable that is required by the project’s hard ordering constraint: the runbook is the artefact the Account Holder follows to populate the 1Password vaults before the infrastructure PR can merge.

Scope (cite of goal.md)

• Goal §“Repositories” — documentation row.
• Goal §“Deliverables” — items 12 (the runbook itself) and 13–17 (the operator artefacts the runbook produces: Creators API Application, four 1Password vault entries).
• Context §“Registration & Operator Setup” — verbatim prerequisites and sign-up flow.
• Context §“Configuration & Env-Var Convention” — the four field names that go into each vault entry (credentialId, credentialSecret, version, associateTag).
• Context §“API Rates, Quotas & Eligibility” — the 30-day eligibility-loss rule, recorded as an operational risk in the runbook’s “Ongoing operations” section.

Personas

The runbook targets two personas with distinct responsibilities. Both must complete their parts for the rollout to succeed; communication between them is part of the procedure.

• accountOwner — the human who is the primary owner of Arda’s Amazon Associates account. Per Amazon’s Register-for-Creators-API page (verbatim quote in context-exploration.md): “Only the primary account owner of the Amazon Associates account can sign up for the Creators API.” Engineering cannot perform these steps on this persona’s behalf. Assume non-technical background — instructions for this persona must be screenshot-friendly, avoid jargon, and explain any tooling step-by-step (notably 1Password Send).
  • Responsibilities: apply for Creators API access; create the Arda Cards Application; capture the credential triple; hand the credentials to devOps securely and out-of-band.
• devOps — the System Administration persona. Has 1Password access to all four Arda-{Env}OAM vaults and to Arda-SystemsOAM, AWS console / CLI access to all partitions, and authorisation to run amm.yml per partition.
  • Responsibilities: receive credentials from accountOwner; populate the four partition vaults; verify accessibility; trigger amm.yml per partition; run the smoke test; notify accountOwner and engineering when the rollout is complete.

Inter-persona communication. Two events must be communicated; the channel is left to the personas’ working agreement (Linear comment on PDEV-446, Slack DM, etc.):

1. accountOwner → devOps — “credentials ready, here’s the Send / DM / dictation.”
2. devOps → accountOwner (and engineering) — “credentials stored, deploys complete, rollout green.”

Repository

Repository	Branch	Worktree
Arda-cards/documentation	jmpicnic/amazon-client-integration (existing — same branch as the planning artefacts)	/Users/jmp/code/arda/projects/amazon-item-import-worktrees/documentation (existing)

Per phases.md, the documentation worktree accumulates updates from multiple streams on the same integration branch. This stream contributes the runbook page; the bff stream contributes the BFF API reference page; both land in the same documentation PR.

Tasks

#	Task	Depends on	Notes
1	Create src/content/docs/process/sre/runbooks/amazon-creators-api-onboarding.md. Front-matter (title, tags: [process, sre, runbook, amazon, onboarding], domain: process, maturity: review, author: "Miguel Pinilla").	—	Match the workspace template at src/content/docs/about/templates/runbook.md.
2	Section: Purpose, personas & overview. State the runbook’s purpose (enable Arda’s Amazon Client Integration to call Creators API in production), reference PDEV-446, and define the two personas (accountOwner, devOps) and their responsibilities (mirroring the “Personas” section of this task-plan). Include a short choreography diagram or numbered list: (1) accountOwner registers + captures credentials; (2) accountOwner → devOps secure handover; (3) devOps populates four vaults; (4) devOps verifies accessibility; (5) devOps triggers amm.yml per partition; (6) devOps runs smoke test; (7) devOps notifies accountOwner and engineering.	1	Section title clearly distinguishes the two personas.
3	Section: Prerequisites (accountOwner). Verbatim Amazon prerequisite quotes from context-exploration.md § “Registration & Operator Setup”. Confirm Arda’s existing Associates standing already satisfies them. List what to do if Arda does NOT yet have final acceptance (file via the Associates Contact Us form; expected wait time is “Amazon-managed, indeterminate”).	1	Quote verbatim with attribution.
4	Section: For accountOwner — Creators API registration. Numbered list, screenshot-friendly, jargon-free (assume non-technical background).	1	All steps in this section are performed by accountOwner.
4.1	Sign in to Amazon Associates Central with the primary-account-owner credentials.	—	Note: only the primary account owner can perform these steps.
4.2	Navigate to Tools → Creators API.	—
4.3	Click Create Application and name it Arda Cards.	—	Single Application for v1.
4.4	Click Add New Credential. Copy or download the Credential ID, Credential Secret, and Version. The Secret is shown only once; lose it and you must generate a new credential. Also note Arda’s existing US Associates Tag — devOps will need it as the fourth field.	—	accountOwner now holds all four values: credentialId, credentialSecret, version, associateTag.
5	Section: For accountOwner — secure handover to devOps. Three acceptable channels in priority order; the runbook walks through each step-by-step (assume non-technical background).	1, 4	Pick the channel that the receiving devOps agrees to use.
5.1	Option A — 1Password Send (preferred). Step-by-step instructions: (a) open 1Password; (b) create a new “Secure Note” titled Amazon Creators API Handover containing the four labelled values (one per line); (c) right-click the note → Share Item via Send (or in the 1Password web app: Send menu → New Send); (d) configure the Send: Expires in 7 days, Maximum views 1, Require one-time password; (e) copy the Send link AND the one-time password; (f) deliver the link to devOps through one channel (Slack DM, email) and the one-time password through a different channel (text/SMS, voice). Include a 1-2 sentence explanation of why two channels — “if a single channel is compromised, neither half is useful on its own.”	4.4	Two-channel split is a standard 1P Send recommendation. Screenshots help — leave a placeholder for inserting them at PR-prep.
5.2	Option B — Slack DM. Direct-message the four values to devOps in Slack. After devOps confirms receipt, delete the message from both sides. Note: Slack message retention may keep an archived copy; Option A is preferred for that reason.	4.4	Acceptable but not preferred.
5.3	Option C — In-person or phone dictation. Read the four values aloud to devOps. devOps reads them back to confirm. Useful when both personas are co-located or have a trusted phone channel.	4.4	No digital trail — preferred over Slack DM if available.
5.4	Notify devOps that the handover is ready. Whichever channel was chosen, post a short message to devOps (Linear comment on PDEV-446, Slack DM — personas’ choice) saying “Amazon Creators API credentials ready via “.	5.1, 5.2, 5.3	This kicks off the devOps section.
6	Section: For devOps — receive and verify the credential triple. Confirm receipt of all four values from accountOwner. If 1Password Send was used, open the Send link with the OTP and copy the four values into a temporary local note (will be deleted after vault population).	5	First devOps step.
7	Section: For devOps — populate the four 1Password vaults. For each of Arda-DevOAM, Arda-StageOAM, Arda-DemoOAM, Arda-ProdOAM: create a single multi-field entry titled Amazon Creators API with fields:	6	Same triple in v1, but stored independently in every vault — vaults are scoped by usage, not uniqueness. The op://Arda-${Vault}/Amazon Creators API/<field> path pattern matches what infrastructure/amm.sh reads at deploy time.
7.1	credentialId ← Credential ID from accountOwner	—	text field.
7.2	credentialSecret ← Credential Secret from accountOwner	—	password / concealed field.
7.3	version ← Version from accountOwner (expected "3.1" for new credentials, but use the actual value Amazon issued)	—	text field.
7.4	associateTag ← Arda’s existing US Associates Tag	—	text field; the public tag.
7.5	After all four vaults are populated, delete the temporary local note from step 6.	7.1–7.4	Don’t leave the credentials in plaintext anywhere local.
8	Section: For devOps — verify vault accessibility. Run the verification one-liner: `for v in DevOAM StageOAM DemoOAM ProdOAM; do op item get “Amazon Creators API” —vault “Arda-${v}” —fields credentialId 2>&1	head -1; done` — must return four non-empty Credential IDs. If any returns an error, fix the vault entry before proceeding.	7
9	Section: For devOps — trigger amm.yml per partition and verify deploy. After the infrastructure PR has merged: run the amm.yml GitHub Actions workflow for each environment in the order dev → stage → demo → prod (dev first, prod last). For each run: confirm the Amplify env vars now include AMAZON_CREATORS_CREDENTIAL_ID, AMAZON_CREATORS_CREDENTIAL_SECRET, AMAZON_CREATORS_CREDENTIAL_VERSION, AMAZON_ASSOCIATE_TAG. For Alpha001/prod, confirm the workflow targets us-east-2 (historical region anomaly).	8	Cross-reference 3-deployment/deployment-plan.md § “Per-partition rollout”.
10	Section: For devOps — smoke test. After each partition’s amm.yml succeeds: run the smoke test described in 3-deployment/deployment-plan.md § “Smoke test” (curl /api/amazon/import with ASIN B08N5WRWNW, verify the v1 DTO shape, exercise the error path, optionally exercise the throttle path). If any partition’s smoke test fails, halt the rollout and follow the rollback procedure for that partition.	9	Reference, don’t duplicate the smoke-test detail.
11	Section: For devOps — completion notification. Once all four partitions are green: post a short message to accountOwner and engineering (channel = personas’ choice) — “Amazon Creators API rollout complete: dev/stage/demo/prod all green, smoke tests pass.” Update PDEV-446 with the per-partition deploy timestamps.	10	Closes the loop.
12	Section: Ongoing operations. Three recurring operational concerns:	1	Both personas have a role here; call out who owns each.
12.1	Eligibility maintenance (accountOwner owns). Per Amazon’s API Rates page (verbatim quote): “your account will lose access to Creators API if it has not generated qualified referring sales for a consecutive 30-day period.” If Arda’s qualified-sales pipeline pauses, Creators API access pauses with it; restored within 2 days of the next qualifying sale. Recommend monitoring by checking the Link Type Performance report on Associates Central monthly.	—	Operational risk, not a blocker.
12.2	Credential rotation (accountOwner + devOps). When credentials need to be rotated (compromise, scheduled hygiene): accountOwner generates a new credential set in Associates Central, then re-runs the secure-handover steps in this runbook. devOps updates all four 1Password vault entries with the new values and re-runs amm.yml for each partition.	—	Re-deploy pulls the new values via op read at amm.sh invocation time.
12.3	Quota awareness (devOps monitors). v1 traffic is human-driven (one paste per user per few seconds at most); the default 1 TPS quota suffices initially. Quota scales with shipped revenue; cap is 10 TPS. No action needed unless throttle errors appear in BFF logs; if they do, devOps notifies engineering.	—
13	Section: References. Link to goal.md, context-exploration.md, the Linear ticket PDEV-446, 3-deployment/deployment-plan.md, and the Amazon-side pages (registration, API Rates, IP License).	1
14	Pre-push: make pr-checks green for the documentation worktree (the runbook is a new page; preview build and link check will validate it).	1–13	The documentation PR also contains other streams’ contributions; final pre-push happens once all streams have committed.
15	CHANGELOG entry in documentation/CHANGELOG.md under the existing project entry ([0.29.0] or whatever’s current at merge time) — the Added section can be amended, not a new release.	—	Each documentation contribution to the same project’s branch shares one CHANGELOG entry, not one per stream.

Acceptance criteria

1. The runbook page renders cleanly in the local Astro preview build (make pr-checks).
2. The runbook clearly distinguishes accountOwner and devOps sections; each persona can follow their part end-to-end without referring to the other persona’s section for procedure (only for context).
3. accountOwner can follow Sections 4 and 5 without engineering assistance, including 1Password Send setup with two-channel delivery (assume non-technical background).
4. devOps can follow Sections 6–11 and produce four valid 1Password vault entries, four green amm.yml runs, and four green smoke-test results.
5. The verification one-liner in Task 8 returns four credential IDs.
6. The runbook covers eligibility-loss recovery (Task 12.1), credential rotation (Task 12.2), and quota awareness (Task 12.3) with persona ownership called out for each.

Merge gate

• CI green on the documentation PR (which combines this stream’s contribution with the bff stream’s BFF API reference page and the planning artefacts).
• No dependency on the other three implementation streams at the documentation-PR level.
• Operationally: the runbook should be merged to main before the Account Holder needs to follow it (so they can reference a stable URL). In practice this means merging the documentation PR can happen any time after the planning artefacts are reviewed; it is not gated on the engineering streams.

Files to be created or modified

New files:

• documentation/src/content/docs/process/sre/runbooks/amazon-creators-api-onboarding.md.

Modified files:

• documentation/CHANGELOG.md (amend the existing project entry’s Added list with a one-liner about the runbook).

References

• ../../goal.md — project goal (deliverables 12–17).
• ../../context-exploration.md § “Registration & Operator Setup”, § “Configuration & Env-Var Convention”, § “API Rates, Quotas & Eligibility”.
• ../../phases.md — stream structure.
• ../../3-deployment/deployment-plan.md — describes the hard ordering constraint that this runbook satisfies.
• ../infrastructure/task-plan.md — infrastructure stream’s merge gate explicitly waits on the runbook’s outputs (the four populated vaults).

---

Copyright: (c) Arda Systems 2025-2026, All rights reserved