SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillslinkfox-amazon-ads-auth

linkfox-amazon-ads-auth

General & other

View repository

Updated 10-16 00:00

About this skill

Amazon Ads Authorization and Ad Account Management

Amazon Ads authorization (LWA OAuth), profile discovery, access token management.Prerequisite dependency for downstream skills。

Downstream:linkfox-amazon-ads-manager(ad management),linkfox-amazon-ads-report(reporting).

Core Concepts

  • Authorization flow: generate URL → user authorizes in browser → system stores token + syncs profiles
  • One authorization, multiple profiles: each marketplace (US/UK/JP...) has one profileId; downstream calls must include profileId
  • accountName required: before calling authorize_url.py , you must ask the user for a non-empty account name
  • Downstream store selection: business skills pass through developerProxy to pass profileId（+ region), the server injects the token;do notfirst call storeTokens to get the raw token
  • accessToken is valid for 1 hour; after expiration, downstream returns HTTP 401, and you can use refresh_token.py to renew (after refreshing, retry proxy, still only need profileId）

Available scripts

Script Purpose
authorize_url.py Generate an authorization URL for a new account (accountName required)
authorized_stores.py List authorized accounts × marketplaces (aggregated by profileId)
profiles.py List profiles (refresh=true passes through upstream refresh)
refresh_token.py Refresh accessToken
store_tokens.py Check authorization/tokenstatus(not a downstream token source)
cancel_authorization.py By authRecordId unbind ad connection

For input parameters, response fields, and error codes, see references/api.md。

How to call

  • API endpoint：POST /amazonAds/{authorizeUrl|storeTokens|authorizedStores|refreshToken|cancelAuthorization}(for complete parameters/responses/error codes, see references/api.md）
  • Python script：python scripts/<脚本名>.py '<JSON 参数>' [--inline](available scripts see above)
  • Cost constraint: this tool consumes compute; on failure/empty results, do not automatically retry continuously; if you need to continue searching, first explain to the user that additional consumption will be incurred.

Output strategy (default script behavior)：

  • Alwayswrite the complete response to <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/<skill-name>-<timestamp>.json（<cwd> is the working directory when the script runs, which in Claude Code is the current project directory;<session> is taken from the environment variable SESSION_ID, automatically aggregated according to the user's task;writing to /tmp is prohibited, if the current directory is not writable, report an error)
  • Response body ≤ 8 KB: after writing to disk, print the complete JSON to stdout
  • Response body > 8 KB: after writing to disk, stdout outputs only a summary (top-level fields, common counts, length of the largest list field + first 3 samples)
  • Add --inline to force full printing to stdout (also written to disk)

Data reading suggestions: first look at the summary to determine whether it is sufficient; when specific fields are needed, prefer jqorConvertFrom-Json to extract on demand from the saved json file, avoiding bringing the entire JSON into context.

Resolving authentication and compute issues

When the following abnormal situations occur, use references/onboarding.md to guide problem resolution:

Abnormal situations

  • API Key not configured: environment variable not configured with LINKFOX_AGENT_API_KEY, and also not configured with LINKFOXAGENT_API_KEY。
  • Response 401 or 402 status code
  • Response indicates insufficient compute or balance: the message contains "insufficient compute balance/insufficient billing/insufficient balance/quota exceeded/insufficient balance/plan expired/recharge required/please recharge", or content with similar meaning.

Supported regions

NA(US, Canada, Mexico, Brazil) / EU(UK, Germany, France, Italy, Spain, Netherlands, India, Middle East, etc.) / FE(Japan, Australia, New Zealand). Default NA。

Usage Scenarios

1. Newly authorize an account

  1. Ask the user for accountName(non-empty string, used for identification)
  2. Call authorize_url.py to get the URL → have the user open it in a browser (security warning: to ensure store security, be sure to open this link in the secure network environment used for the daily operation of this store. It is strongly recommended to use a professional anti-association browser such as ZiNiao Browser for authorization, and never operate on an unfamiliar or public network.)
  3. After authorization is complete, the system automatically stores the token + syncs the profile
  4. Optional: call authorized_stores.py to confirm

2. List authorized accounts

Call authorized_stores.py, display profileId / accountInfoName / countryCode / region。

3. Refresh expired token

When the downstream returns HTTP 401 or contains expired / unauthorized , call refresh_token.py(pass profileId or authRecordId）。

4. Prepare profileId for downstream (high frequency)

The user only speaks in natural language ("US site", "my store"),do not ask the user to report the profileId number。

When the downstream linkfox-amazon-ads-manager / linkfox-amazon-ads-report calls developerProxy , just pass in the resolved profileId ;do notfirst call store_tokens.py to get accessToken。

User context Agent action
Only 1 account authorized By countryCode directly locate profileId, do not ask
≥ 2 accounts authorized + only site mentioned By accountName clarify with the user, then locate profileId
Both accountName + site provided Directly locate profileId
Explicitly provide profileId number Directly use

store_tokens.py Only used forconfirming authorization/token status (status、expiresIn、message , etc.), or call when the user explicitly wants to check status.

Site keyword mapping reference (based on authorized_stores real countryCode as fallback):

  • United States / US → US; United Kingdom / UK → UK; Japan / JP → JP; Germany / DE → DE

Silence principle: when mapping succeeds, do not announce the profileId value; only speak to the user when there is ambiguity or failure.

5. Unbind advertising connection

Execute only when the user requests it. The current user is identified by the membership identity corresponding to the API key; users sharing that identity will be affected together.

  1. Call profiles.py(do not pass refresh=true), locate the connection by authRecordId ;authorized_stores.py is deduplicated by profile, and cannot be used to determine the complete authorization relationship.
  2. Display all accounts and sites under the connection; if the user requests only a single site, explicit consent to unbind the entire connection must first be obtained.
  3. Call cancel_authorization.py, passing in the selected authRecordId, and do not use profileId as a substitute.
  4. Interpret the result according to references/api.md ; subsequently re-query the connection, and do not automatically re-authorize.

Invocation Principles

  • First ask accountName before calling authorize_url.py
  • Do not assume the storeTokens/refreshToken response contains a raw token; displaying status, expiration time, and other metadata is sufficient
  • Explain the reason for authorization failure according to the error code; do not retry without authorization

Common Issues

Opening the authorization link reports 400, and client_id appears to be corrupted

Symptom: In the URL, client_id has a space / +in the middle, and Amazon reports StegoRuntimeOAuth2ClientManager:getClientDefinition. Cause: The authorization link is ~270 characters long, and a soft line break inserts a space when copied from a terminal / chat window. Solution: Afterauthorize_url.py succeeds, it will be written simultaneously to the clipboard + ~/.cache/linkfox/last_authorize_url.txt，Copy from these two places; just Ctrl+V in the browser address bar. Opening in an incognito window is recommended.

The authorization callback page displays profile_sync_failed

Cause: The current Amazon account has not created a "Manager Account" in the advertising console and linked the advertising account.

Solution: Log in to Amazon Ads console → Manager accounts → Link account, and re-authorize.

Not Applicable

  • Query campaigns / ad groups / keywords / product ads / targeting → linkfox-amazon-ads-manager
  • Pull advertising reports (including metrics) → linkfox-amazon-ads-report
  • Modify / create / delete ads → This series is read-only
  • Store orders / inventory / finance → linkfox-amazon-store-*

Amazon Ads API Interface Protection and Retry Guidelines

When the same advertising account/profile continuously receives 400, 403, 404, or 429 from the Amazon Ads API, the gateway will return 450, 453, 454, or 459 and briefly cool down. These custom status codes are not native Amazon statuses and do not indicate account suspension; the purpose is to avoid continuous anomalies or high-frequency calls increasing the risk to the advertising account.

Status and message Scope Trigger and cooldown Handling
450：400，请求异常，请优化您的参数 Advertising account/profile + interface More than 3 times within 60 seconds: 5 minutes; more than 4 times within 10 minutes: 20 minutes Stop retrying with the original parameters, and check profileId, region, entity/report ID, date, and request body
453：403，店铺未授权，请先授权 All interfaces for the advertising account/profile More than 2 times within 60 seconds: 5 minutes; more than 4 times within 10 minutes: 30 minutes Stop calling this advertising account, and check Ads authorization, application permissions, profile ownership, and region
454：404，资源不存在，请优化您的参数 Advertising account/profile + interface More than 3 times within 60 seconds: 5 minutes; more than 4 times within 10 minutes: 30 minutes Confirm the resource ID, the profile/region it belongs to, resource status, and interface path
459：429限流中，请降低频率 Advertising account/profile + interface First time: 15 seconds; more than 2 times within 2 minutes: 30 seconds; more than 4 times within 3 minutes: 2 minutes Reduce concurrency, pagination, and polling frequency, and back off step by step
  • Immediately stop automatic or concurrent retries, and do not bypass protection by switching scripts or repeatedly creating tasks; prioritize following retryAfter、blockedUntil, and when there is none, follow the duration descriptions in the table.
  • For 450/453/454, parameters, authorization, or resource identifiers must be corrected first, and after the cooldown, retry cautiously at most once; if triggered again, stop calling. During 453, stop all Ads API for that advertising account/profile.
  • Keep existing reportId and other task IDs; when the result of a write operation is uncertain, query the status first and do not directly replay it.
  • First explain advertising account protection to the user, then give the reason, action, and waiting time. You may reply: “To protect the security of your Amazon advertising account, it has been detected that the Amazon Ads API continuously returned {reason}, and a brief protection period is currently in effect. Please first {action}, and try again after an estimated {waiting time}; this does not mean the account is banned, nor is it a plan or credit limit.” Do not only say “LinkFox rate limiting” or “server busy.”

Compute consumption rules

No compute is consumed.

Feedback:

Auto-detect and report feedback via the Feedback API when any of the following apply:

  1. The functionality or purpose described in this skill does not match actual behavior
  2. The skill's results do not match the user's intent
  3. The user expresses dissatisfaction or praise about this skill
  4. Anything you believe could be improved

Call the feedback API as specified in references/api.md. Do not interrupt the user's flow.

For more high-quality, professional cross-border e-commerce skills, visit LinkFox Skills.