Runbook: Amazon Creators API Onboarding

Author: Miguel Pinilla Date: 2026-05-07 Last Verified: 2026-05-07 Environments: dev | stage | demo | prod Linear: PDEV-446

Purpose

This runbook enables Arda’s Amazon Client Integration (PDEV-446) to call the Creators API in production. It walks through:

1. Amazon Creators API registration by the account owner.
2. Secure credential hand-off from the account owner to the devOps engineer.
3. 1Password vault population, deploy pipeline execution, and smoke testing by devOps.

Both personas must complete their parts in sequence for the rollout to succeed. Neither can substitute for the other: Amazon restricts Creators API registration to the primary account owner, and vault population requires the devOps engineer’s 1Password and AWS access.

Personas

Persona	Who	Background
accountOwner	Primary owner of Arda’s Amazon Associates account	Non-technical; no AWS access and no Arda 1Password vault access required. Needs the ability to create a 1Password Send via personal/free 1Password account (preferred), or fall back to Slack DM + phone for the secret. See Section 5.1.
devOps	System Administrator	1Password access to all Arda-{Env}OAM vaults; AWS console/CLI access to all partitions; authorisation to run amm.yml

Choreography Overview

The steps below are numbered in execution order. Sections 3–5 are accountOwner responsibilities; sections 6–11 are devOps responsibilities.

1. accountOwner: verify prerequisites (Section 3)
2. accountOwner: register for Creators API, create Application, capture credentials (Section 4)
3. accountOwner → devOps: deliver credentials securely (Section 5)
4. accountOwner → devOps: notification — "credentials ready" (Section 5.4)
5. devOps: receive and verify credential values (Section 6)
6. devOps: populate all four partition vaults (Section 7)
7. devOps: verify vault accessibility (Section 8)
8. devOps: trigger amm.yml per partition in order dev → stage → demo → prod (Section 9)
9. devOps: smoke test each partition after deploy (Section 10)
10. devOps → accountOwner + engineering: completion notification (Section 11)

---

Section 3: Prerequisites — accountOwner

Only the primary account owner of the Amazon Associates account can sign up for the Creators API.

Before proceeding, confirm the following (verbatim from Amazon’s “Register for Creators API” page):

“Before you register for the Creators API, you must have an Amazon Associates account that has been reviewed and received final acceptance into the Amazon Associates Program.”

“Creators API sign up is available only to associates who have referred qualified sales and have been accepted into the program.”

Arda’s existing US Associates standing already satisfies both prerequisites. No action needed unless Associates Central shows the account is not in good standing.

If Arda does NOT yet have final acceptance: File a request through the Associates Contact Us form and wait for Amazon’s acceptance email. Wait time is Amazon-managed and indeterminate. Do not proceed to Section 4 until the account has final acceptance.

---

Section 4: For accountOwner — Creators API Registration

All steps in this section are performed by accountOwner. These steps cannot be delegated to engineering.

You will capture four values by the end of this section:

Value	Label in this runbook	Notes
Credential ID	credentialId	Issued by Amazon; public by design
Credential Secret	credentialSecret	Shown only once. Copy it immediately — lose it and you must generate a new credential.
Version	version	Expected "3.1" for new credentials; use the value Amazon issues
Associates Tag	associateTag	Arda’s existing US Associates Tag (find it on your Associates Central dashboard)

Step 4.1: Sign in to Amazon Associates Central

Open a browser and go to https://affiliate-program.amazon.com. Sign in with the primary account owner’s Amazon credentials (the account that owns Arda’s Associates Program membership).

Step 4.2: Navigate to Creators API

In the Associates Central menu, click Tools, then click Creators API.

Step 4.3: Create an Application

Click Create Application. When prompted for a name, enter:

Arda Cards

This creates a single Application for the v1 integration. Click Save or Create to confirm.

Step 4.4: Add a New Credential and Copy the Values

Inside the Arda Cards Application, click Add New Credential.

Amazon will display three values:

• Credential ID
• Credential Secret — this is shown only once. Copy it now before closing the dialog.
• Version

Copy all three values to a temporary note (your own notes app, or on paper). You will package them securely in Section 5 and delete the temporary note afterward.

Also locate Arda’s US Associates Tag on your Associates Central dashboard (usually shown in the upper-right corner or under your account settings). Add it to your temporary note as the fourth value (associateTag).

You now have all four values needed for the hand-off. Proceed to Section 5.

---

Section 5: For accountOwner — Secure Handover to devOps

All steps in this section are performed by accountOwner.

Choose one of the three options below. Option A (1Password Send) is preferred. Agree with devOps on which channel to use before starting.

Section 5.1: Option A — 1Password Send (Preferred)

1Password Send lets you share sensitive information securely. The key safety rule: deliver the Send link and the one-time password (OTP) through two different channels. If one channel is compromised, neither half is useful on its own.

Step-by-step:

1. Open the 1Password app on your computer or phone (or go to 1password.com and sign in).
2. Create a new Secure Note (look for a ”+” button or “New Item” → “Secure Note”).
3. Title the note: Amazon Creators API Handover.
4. In the note body, enter the four values on separate lines:

   credentialId: <the Credential ID from Step 4.4>
   credentialSecret: <the Credential Secret from Step 4.4>
   version: <the Version from Step 4.4>
   associateTag: <Arda's US Associates Tag>

5. Save the note.
6. Share the note via Send:
   • In the 1Password desktop app: right-click the note → Share → Share via 1Password Send.
   • In the 1Password web app: open the note → click the Send button (or three-dot menu → Share via Send).
7. Configure the Send settings:
   • Expires in: 7 days
   • Maximum views: 1
   • Require one-time password: enabled (turn this on)
8. Click Create Send (or Generate Link).
9. 1Password will show you two things: a Send link (a URL) and a one-time password (a short code).
10. Deliver the Send link and the OTP through two different channels:
    • Send the link via one channel (for example: Slack DM or email).
    • Send the OTP via a different channel (for example: text message / SMS or voice call).

Why two channels? If someone has access to only one channel (for example, they can read your Slack messages), they get either the link or the OTP — but not both. The credential is safe until both halves arrive.

After devOps confirms receipt and vault population, delete the temporary note from Step 4.4 from your own device.

Section 5.2: Option B — Slack Direct Message

Send the four values directly to devOps as a Slack DM. After devOps confirms receipt, delete the message from your side and ask devOps to delete it from their side as well.

Note: Slack message retention may keep an archived copy even after deletion. Option A is preferred for this reason. Use Option B only if 1Password Send is not available.

Section 5.3: Option C — In-Person or Phone Dictation

Read the four values aloud to devOps. Ask devOps to read them back to confirm each value. This option leaves no digital record and is preferred over Option B when both personas are in the same location or have a trusted phone connection.

Section 5.4: Notify devOps That the Handover Is Ready

Once you have delivered the credentials via the chosen channel, send a short notification to devOps through any agreed channel (Linear comment on PDEV-446, Slack DM, etc.):

“Amazon Creators API credentials ready via <channel you used>.”

This message kicks off the devOps section. accountOwner’s work is complete until Section 11.

---

Section 6: For devOps — Prerequisites and Receive Credential Values

All steps from here are performed by devOps.

Section 6.0: Service Account Token (already provisioned)

The amm.yml GitHub Actions workflow reads the Amazon credential triple from the four Arda-{Env}OAM partition vaults via op read. It does this using a 1Password Service Account whose token is stored as the OP_SERVICE_ACCOUNT_TOKEN GitHub Organisation secret.

Item	Value
GH Org secret	OP_SERVICE_ACCOUNT_TOKEN
1Password Service Account	IAC-SCRIPTS Service Account Token (stored in Arda-SystemsOAM)
Required vault scope	Read access to Arda-DevOAM, Arda-StageOAM, Arda-DemoOAM, Arda-ProdOAM, and Arda-SystemsOAM

This is shared infrastructure used by other CI workflows (e.g. external-resources-drift.yml). The devOps engineer does not provision it for this project specifically — it already exists in the GitHub Organisation.

Verify the token’s scope covers all four partition vaults by running the following from any workstation where you have the OP_SERVICE_ACCOUNT_TOKEN value available (substitute the token):

OP_SERVICE_ACCOUNT_TOKEN=<token-value> \
  op item get "Amazon Creators API" \
    --vault "Arda-DevOAM" \
    --fields credentialId 2>&1 | head -1

Replace Arda-DevOAM with each of Arda-StageOAM, Arda-DemoOAM, and Arda-ProdOAM in turn. Each must return a non-empty Credential ID rather than an [ERROR] 401 or vault-not-found error. A [ERROR] response means the service account’s 1Password vault access does not cover that vault and must be updated before amm.yml can deploy to that partition.

If the token is rotated or its vault access is revoked: the token is managed via the IAC-SCRIPTS Service Account Token item in the Arda-SystemsOAM 1Password vault. Vault-access changes require a 1Password account administrator. Contact whoever owns the IAC-SCRIPTS service account in 1Password, then update the OP_SERVICE_ACCOUNT_TOKEN GH Org secret with the new token value using the tools/set-gha-repo-secret.sh script in the infrastructure repository.

Confirm receipt of all four values from accountOwner:

Field	Expected
credentialId	Non-empty string
credentialSecret	Non-empty string (treat as a password)
version	Non-empty string, expected "3.1" for new credentials
associateTag	Non-empty string (Arda’s US Associates Tag)

If 1Password Send was used (Option A): Open the Send link in a browser, enter the OTP when prompted, and copy all four values into a temporary local note (for example, a text file in /tmp/ or a scratch note in your editor). You will delete this note after completing Section 7.

If Slack DM was used (Option B): Copy the values into a temporary local note.

If dictated (Option C): Enter the values directly as you write them down.

Verify all four values are present before proceeding. If any value is missing or looks truncated, ask accountOwner to resend.

---

Section 7: For devOps — Populate the Four 1Password Vaults

Create one multi-field entry titled Amazon Creators API in each of the four partition vaults. Use the same four values in every vault. Even though v1 uses the same credential triple in all environments, each vault gets its own independent entry so any future per-environment rotation requires no infrastructure change.

Vault	Partition
Arda-DevOAM	Alpha002 / dev
Arda-StageOAM	Alpha002 / stage
Arda-DemoOAM	Alpha001 / demo
Arda-ProdOAM	Alpha001 / prod

For each vault, create the entry with the following fields:

Field name	Field type	Value
credentialId	Text	Credential ID from accountOwner
credentialSecret	Password (concealed)	Credential Secret from accountOwner
version	Text	Version from accountOwner (expected "3.1")
associateTag	Text	Arda’s US Associates Tag

Using the 1Password CLI (op), the entry can be created without exposing the credential secret in shell history or process arguments by feeding a JSON template through stdin. Run this once per vault, substituting <vault> with each of Arda-DevOAM, Arda-StageOAM, Arda-DemoOAM, Arda-ProdOAM:

# Read the credentialSecret interactively (does not echo, no shell history).
read -rs -p "credentialSecret: " AMAZON_CREDENTIAL_SECRET; echo

# Build the item template and pipe it to `op item create` via stdin.
op item template get "Secure Note" \
  | jq --arg id    "<credentialId>" \
       --arg sec   "$AMAZON_CREDENTIAL_SECRET" \
       --arg ver   "<version>" \
       --arg tag   "<associateTag>" '
      .title  = "Amazon Creators API"
    | .fields = [
        {label:"credentialId",     type:"STRING",   value:$id},
        {label:"credentialSecret", type:"CONCEALED",value:$sec},
        {label:"version",          type:"STRING",   value:$ver},
        {label:"associateTag",     type:"STRING",   value:$tag}
      ]' \
  | op item create --vault "<vault>" -

unset AMAZON_CREDENTIAL_SECRET

op item create - reads the assembled JSON from stdin, so the secret never appears on a command line, in ~/.bash_history, or in ps-visible process arguments. The non-secret fields (credentialId, version, associateTag) remain inline for clarity; substitute them per the values delivered by the accountOwner.

Alternatively, create the entries manually via the 1Password desktop app: open the vault → click + → Secure Note → set the title and add one field per row. The desktop app never exposes field values to the shell.

The op:// path for each field (used by amm.sh at deploy time) follows the pattern:

op://Arda-{Env}OAM/Amazon Creators API/<field>

For example: op://Arda-DevOAM/Amazon Creators API/credentialId.

Step 7.5: Delete the temporary local note

After all four vaults are populated, delete the temporary local note you created in Section 6. Do not leave the credential values in plaintext anywhere on your local machine.

---

Section 8: For devOps — Verify Vault Accessibility

Run the following verification one-liner to confirm that all four vaults are accessible and contain a non-empty credentialId:

for v in DevOAM StageOAM DemoOAM ProdOAM; do
  echo -n "Arda-${v}: "
  op item get "Amazon Creators API" --vault "Arda-${v}" --fields credentialId 2>&1 | head -1
done

Expected output: four lines, each showing a non-empty Credential ID value. Example:

Arda-DevOAM: ABCDEF1234567890
Arda-StageOAM: ABCDEF1234567890
Arda-DemoOAM: ABCDEF1234567890
Arda-ProdOAM: ABCDEF1234567890

If any vault returns an error or an empty value, correct the vault entry for that environment before proceeding. Do not trigger amm.yml until all four vaults return non-empty values.

This is the same gate that the infrastructure PR’s deploy verification enforces. Post the output of this command as a comment on the infrastructure PR body and on PDEV-446 to satisfy merge gate #1b.

---

Section 9: For devOps — Trigger amm.yml Per Partition and Verify Deploy

Prerequisite: the infrastructure PR must have merged before this section. See the Deployment Plan for merge order.

Run the amm.yml GitHub Actions workflow for each partition in the order listed below. Deploy one partition at a time; run the smoke test (Section 10) before moving to the next.

Order	Partition	AWS Account	Region
1	Alpha002/dev	Alpha002	us-east-1
2	Alpha002/stage	Alpha002	us-east-1
3	Alpha001/demo	Alpha001	us-east-1
4	Alpha001/prod	Alpha001	us-east-2 (region anomaly — verify in workflow logs)

For each partition:

1. Go to the infrastructure repository’s GitHub Actions tab and locate the amm.yml workflow.
2. Click Run workflow, select the target partition (e.g. Alpha002/dev), and start the run.
3. Wait for the workflow to complete (green checkmark).
4. Confirm the Amplify environment variables now include:
   • AMAZON_CREATORS_CREDENTIAL_ID
   • AMAZON_CREATORS_CREDENTIAL_SECRET
   • AMAZON_CREATORS_CREDENTIAL_VERSION
   • AMAZON_ASSOCIATE_TAG
5. For Alpha001/prod: verify in the workflow logs that the deploy targets region us-east-2. This is an existing historical anomaly — the prod Amplify app lives in us-east-2 while all other partitions use us-east-1.
   • Via amm.yml (normal path): no manual override is needed. The workflow uses purpose-configuration-action to set aws-region from partition-config before invoking amm.sh, so the correct region is already active.
   • Via local amm.sh invocation (manual / emergency path): the operator must explicitly pass --region us-east-2, OR ensure the active Admin-Alpha1 AWS profile is configured with us-east-2 as its default region. The script does not auto-detect the region when run outside CI. Example:

     amm.sh Alpha001 prod --region us-east-2

If a workflow run fails, check the workflow logs for errors from op read (1Password access) or aws cloudformation deploy (CFN stack errors) and resolve before retrying.

---

Section 10: For devOps — Smoke Test

After each partition’s amm.yml run completes, run the smoke test for that partition before proceeding to the next. The full smoke-test procedure (ASIN B08N5WRWNW, expected response shape, error-path exercise, throttle-path exercise) is defined in the Deployment Plan § “Smoke test”. Follow that procedure.

If any partition’s smoke test fails:

1. Stop the rollout. Do not deploy to subsequent partitions.
2. Follow the rollback procedure in the Deployment Plan for the failing partition.
3. Investigate the failure (check BFF logs in CloudWatch for the partition, verify env vars are set, verify vault values are correct).

Do not proceed to Section 11 until all four partitions pass their smoke tests.

---

Section 11: For devOps — Completion Notification

Once all four partitions are deployed and smoke-test green, send a completion notification to accountOwner and engineering through any agreed channel (Linear comment on PDEV-446, Slack, etc.):

“Amazon Creators API rollout complete: dev/stage/demo/prod all green, smoke tests pass.”

Also update PDEV-446 with the per-partition deploy timestamps.

---

Section 12: Ongoing Operations

Section 12.1: Eligibility Maintenance — owned by accountOwner

Creators API access is conditional on Arda maintaining qualified referring sales. Per Amazon’s API Rates page (verbatim):

“your account will lose access to Creators API if it has not generated qualified referring sales for a consecutive 30-day period. If you lose access to Creators API, you can continue to use other product linking tools, such as Site Stripe and generate revenue. You will regain access to Creators API within two days after your referred sales are shipped.”

Recommendation: accountOwner should check the Link Type Performance report on Associates Central monthly to confirm that Arda’s qualified-sales pipeline is active. If a 30-day gap in qualifying sales is approaching (for example, due to a site outage), notify engineering promptly — Creators API access will pause, and the BFF route will return AMAZON_API_UNAVAILABLE until access resumes.

Access restoration is automatic (within two days of the next qualifying sale) and does not require re-registration.

Section 12.2: Credential Rotation — owned by accountOwner and devOps

When credentials need to be rotated (compromise detected, scheduled security hygiene, or at Amazon’s request):

1. accountOwner: go to Associates Central → Tools → Creators API → Arda Cards Application → Add New Credential. Copy the new Credential ID, Credential Secret, and Version.
2. accountOwner: follow Section 5 of this runbook to deliver the new credential triple to devOps securely.
3. devOps: update all four partition vaults (Arda-DevOAM, Arda-StageOAM, Arda-DemoOAM, Arda-ProdOAM) with the new values.
4. devOps: re-run the verification one-liner from Section 8 to confirm the new values are accessible.
5. devOps: trigger amm.yml for each partition in the order from Section 9. The deploy script reads the updated vault values via op read at invocation time; no code change is needed.
6. devOps: run the smoke test from Section 10 for each partition.

After rotation is complete, the old credential set can be deleted from Associates Central if desired (select the credential in the Application and click Delete). This does not affect the new credentials.

Section 12.3: Quota Awareness — monitored by devOps

The initial Creators API allocation is 1 request per second (TPS) and 8,640 requests per day (TPD). v1 traffic is human-driven — one paste per user session — so steady-state usage is well below these limits.

Quota scales automatically with shipped revenue: +1 TPS for every $4,320 in referred revenue over the previous 30-day period, up to a maximum of 10 TPS.

No action needed unless ThrottleException errors appear in BFF logs (HTTP 429 responses from the Creators API). If throttle errors appear: devOps notifies engineering so the BFF’s backoff behaviour can be reviewed and a quota increase request to Amazon can be evaluated.

---

References

• Amazon Client Integration — Project Goal
• Amazon Client Integration — Context Exploration — verbatim API rates, eligibility rules, and registration prerequisites
• Amazon Client Integration — Deployment Plan — merge order, per-partition rollout choreography, smoke test procedure, rollback
• Secrets Vault — Arda-{Env}OAM vault layout and access conventions
• PDEV-446 on Linear — project tracking
• Amazon Creators API — Register for Creators API
• Amazon Creators API — API Rates
• Associates Program IP License

---

Change History

Date	Author	Change
2026-05-07	Miguel Pinilla	Initial version — Amazon Client Integration v1 (PDEV-446)