linkfox-amazon-store-auth

Amazon Store Authorization and Management

This skill is responsible for OAuth authorization for Amazon seller stores, the list of authorized stores, authorization status queries, token refresh, and local authorization cancellation, and is a prerequisite dependency for all downstream operations such as pulling reports, querying inventory, and syncing orders. Downstream business passes developerProxy into sellerId+region and that is sufficient;there is no needto first obtain a raw token.

📌 Related skill: if the user needs to pull Amazon store reports(inventory / orders / sales / financial reports, etc.), please switch to linkfox-amazon-store-report. That skill depends on the authorization and token capabilities provided by this skill.

Core Concepts

The Selling Partner API is the official interface provided by Amazon for sellers. This skill is responsible for the OAuth 2.0 authorization flow and token lifecycle management:

Authorization flow: generate authorization URL → user completes authorization on Amazon → Amazon calls back with an authorization code → the system exchanges the authorization code for a token → the token is securely stored.

Store name (sellerName) is required: before calling /spApi/authorizeUrl ,you mustask the user for and obtain a clear, non-empty store name. It is used to mark the account in the "authorized store list"; do not leave it empty or use a blank string.

Token lifecycle：accessToken usually expires in 1 hour;refreshToken is used to renew a new accessToken。

Data Fields

Authorization URL Response

Field	Type	Description
authorizeUrl	string	the Amazon authorization link for the user to open in a browser

Authorized Store Item

Field	Type	Description
sellerId	string	Amazon Seller ID (Merchant ID)
sellerName	string	store name (required during authorization)
region	string	marketplace region code NA / EU / FE

Store Tokens (authorization status, not raw token issuance)

POST /spApi/storeTokens returnsstatus and metadata(specific fields are subject to the gateway), for confirming whether the authorization is valid and when it expires.Do notuse the response as the token source for downstream developerProxy .

Field	Type	Description
status	string	authorization/token status (such as valid, expired, missing)
authRecordId	integer	authorization record ID (if any)
expiresIn	integer	seconds until accessToken expires (if any)
tokenExpiresAt	string	absolute expiration time (if any)
message	string	additional notes
errcode / errmsg	integer / string	gateway error (on failure)

Compatibility note: older gateways may still return accessToken/refreshToken；Agent should notbe preferentially read or passed downstream. Downstream should use sellerId+region to call developerProxy。

Supported Regions

Code	Name	Marketplaces
NA	North America	United States, Canada, Mexico
EU	Europe	United Kingdom, Germany, France, Italy, Spain, Netherlands, etc.
FE	Far East	Japan, Australia, Singapore, India

The default region is NA; when unbinding, specify the target region according to Scenario 5.

How to call

• API endpoint：POST /spApi/{authorizeUrl|storeTokens|authorizedStores|refreshToken|cancelAuthorization}(for complete parameters/responses/error codes, see references/api.md）
• Python script：python scripts/<脚本名>.py '<JSON 参数>' [--inline](Available scripts are shown above)
• Cost constraints: This tool consumes compute; failed/empty results must not automatically trigger continuous retries; when further retrieval is needed, first explain to the user that additional consumption will be incurred.

Output strategy (default script behavior)：

• Alwayswrite the full response to <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/<skill-name>-<timestamp>.json（<cwd> is the working directory when the script executes, 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 full 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 recommendations: First look at the summary to determine whether it is sufficient; when specific fields are needed, prefer using jqorConvertFrom-Json to extract on demand from the saved json file, avoiding bringing the entire JSON into context.

Resolve authentication and compute issues

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

Abnormal situations

• API Key not configured: The environment variable is not configured LINKFOX_AGENT_API_KEY, and 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/package expired/recharge required/please recharge", or content with similar meaning.

Usage Scenarios

Scenario 1: Authorize New Store

User request: "I want to authorize my Amazon North America marketplace"

Steps：

1. Ask for the store name sellerName(if the user has not provided it)./spApi/authorizeUrl Require sellerName to be a non-empty string; explain to the user that this is only a label for identifying the store in LinkFox, and it is recommended to keep it consistent with the name in the Seller Central backend.
2. Call /spApi/authorizeUrl, passing in region and sellerName
3. Give the returned authorizeUrl to the user, and have them open it in a browser
4. The user completes authorization on Amazon → Amazon calls back to the system → the system automatically saves the authorization
5. Optional: call /spApi/authorizedStores to confirm successful authorization

Scenario 2: View Authorized Stores

User request: "List the Amazon stores I have authorized"

Steps：

1. Call /spApi/authorizedStores
2. Display the store list (sellerName / sellerId / region)
3. Sort by sellerId, region

Scenario 3: Refresh Expired Token

User request: "My store's token has expired, help me refresh it"

Steps：

1. Call /spApi/refreshToken, passing in sellerId(optional region）
2. Return refreshstatus and metadata(such as status、message、expiresIn); the server updates the token
3. Downstream can directly retry developerProxy(passing in the same sellerId+region），no need toread the raw token

Scenario 4: Query Store Token Status

User request: "Check the authorization/token status of store A123 in the North America marketplace"

Steps：

1. Call /spApi/storeTokens, passing in sellerId and region
2. Show the userstatus fields（status、expiresIn、tokenExpiresAt、message , etc.)
3. Do nottreat the response as the downstream proxy's token; business calls should directly carry sellerId+region

Scenario 5: Cancel Local Authorization

User request: "Cancel/unbind authorization for my Amazon store"

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

Steps：

1. Determine /spApi/authorizedStores from the user-specified target or sellerId + region; do not use a default region, and if ambiguous, have the user choose.
2. Explain that unbinding covers the entire region; if the user only requests a single site, explicit consent for unbinding the entire region must first be obtained.
3. Call /spApi/cancelAuthorization, passing in the selected sellerId and region。
4. Interpret the result according to references/api.md ; subsequently re-query the store and do not automatically re-authorize.

Scenario 6: Prepare Account Selector for Any Store Operation (Standard Preparation Workflow)

When the user makes any request involving seller backend data (pulling reports, checking inventory, viewing orders, etc.),this skill handles the preceding "select store → confirm authorization", and the specific business is taken over by the corresponding downstream skill.

Steps：

1. List authorized stores: call /spApi/authorizedStores
2. Have the user select a store: if there are multiple stores, ask the user to explicitly choose which one, and determine sellerId and region
3. (Optional) call /spApi/storeTokens only for status confirmation(if expired, then first refreshToken）
4. Hand sellerId+region to the downstream skill(for example linkfox-amazon-store-report), and the downstream directly calls developerProxy

Why this workflow is critical：

• The user may have authorized multiple stores in different regions at the same time
• Each store's token and permissions are independent of one another
• Must use the sellerId+regionmatching the store; skipping "store selection" will cause ambiguity and errors

Display Rules

1. Have the store name before generating the authorization link: if the user does not provide sellerName，you must ask first; calling with an empty value is not allowed /spApi/authorizeUrl。
2. Present data only: displaying authorization results, store lists, and token information is sufficient; do not make business suggestions.
3. Security awareness: if the response contains a legacy token field, do not display it in plaintext; prefer to present status / expiration time and other metadata.
4. Clear guidance: when returning the authorization link, clearly tell the user to open it in a browser and complete authorization.
5. Error explanation: when authorization fails, explain the reason based on the error code and give suggestions.
6. Success confirmation: after authorization is complete, confirm with the user, and optionally display the store's basic information.

Important Limitations

• sellerName required：/spApi/authorizeUrl : must pass a non-empty sellerName; the script and agent must verify before calling.
• Token validity period：accessToken expires in 1 hour and must be refreshed promptly.
• Region-specific: each store authorization is bound to a specific region, and different regions must be authorized separately.
• User isolation: users can only view/manage stores they have authorized.
• Callback whitelist: the system callback URL must be whitelisted at the authorizing party (Ziniao).

User Expression & Scenario Quick Reference

Applicable — authorization and token management scenarios:

User Says	Scenario
"Authorize my Amazon store" / "Authorize my Amazon store"	New store authorization
"Show my authorized Amazon stores" / "Show my authorized stores"	List authorized stores
"令牌过期了" / "My token expired"	Refresh token
"查 XXX 店铺授权状态" / "Check store token status"	Query authorization status (storeTokens)
"绑定我的亚马逊账号" / "Connect my Amazon seller account"	New store authorization
"取消授权" / "解绑这个亚马逊店铺" / "Disconnect seller account"	Local cancel/unbind authorization

Not applicable — Outside this skill's scope:

• Pull Amazon reports → Please use linkfox-amazon-store-report
• Product listing management, order processing, inventory management, ad delivery → handled by other skills

Boundary judgment：

• This skill is only responsible for "authorization + store management + token refresh/status query + preparing sellerId+region store selection info for downstream".
• Do notfor downstream developerProxy call storeTokens to get raw accessToken(unless compatible with very old clients and the user explicitly requests it).
• When the user wants to do specific seller backend business (such as pulling reports):
  1. This skill executes Scenario 6's standard prerequisite process (store selection)
  2. then switch to the corresponding downstream skill, directly developerProxy + sellerId+region
• Do not bypass this skill to directly call specific Amazon open APIs.

Quick Reference

Authorization & Token Management APIs

API	Path	Purpose	Auth Required
Get Authorization URL	/spApi/authorizeUrl	Generate authorization link (requires sellerName)	✅ Yes
List Authorized Stores	/spApi/authorizedStores	Query the user's store list	✅ Yes
Refresh Token	/spApi/refreshToken	Refresh access token	✅ Yes
Query Store Token Status	/spApi/storeTokens	Query a store's authorization/token status (not a downstream token source)	✅ Yes
Cancel Authorization	/spApi/cancelAuthorization	Locally cancel/unbind the current user's store authorization	✅ Yes

For detailed request parameters, response structure, and error codes, see references/api.md. For the complete authorization flow diagram, see references/authorization-flow.md. For quick start examples, see references/quick-start.md。

Amazon SP-API Interface Protection and Retry Guidelines

When the same store continuously receives 400, 403, 404, or 429 from the Amazon SP-API, the gateway returns 450, 453, 454, or 459 and briefly cools down. These custom status codes are not native Amazon statuses, nor do they indicate account suspension; the purpose is to avoid expanding store risk due to continuous anomalies or high-frequency calls.

Status and message	Scope	Trigger and cooldown	Handling
450：400，请求异常，请优化您的参数	Store+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 required fields, marketplace, ID, date, and request body
453：403，店铺未授权，请先授权	All store interfaces	More than 2 times within 60 seconds: 5 minutes; more than 4 times within 10 minutes: 30 minutes	Stop calls to that store, and check authorization, permissions, store ownership, and region
454：404，资源不存在，请优化您的参数	Store+interface	More than 3 times within 60 seconds: 5 minutes; more than 4 times within 10 minutes: 30 minutes	Confirm the resource ID, owning store/site, resource status, and interface path
459：429限流中，请降低频率	Store+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, if not, follow the duration description in the table.
• For 450/453/454, you must first correct the parameters, authorization, or resource identifier, and after the cooldown period retry cautiously at most once; if triggered again, stop calling. During 453, stop all SP-API for that store.
• Keep the existing reportId、feedId 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 store protection to the user, then give the reason, handling, and waiting time. You may reply: "To protect the security of your Amazon store, it has been detected that Amazon SP-API continuously returned {reason}, and a brief protection period is currently in effect. Please first {handling action}, and try again after an estimated {waiting time}; this does not mean the account is banned, nor is it a plan or computing power limit." Do not only say "LinkFox rate limiting" or "server busy".

Computing power consumption rules

No computing power is consumed.

Feedback：

When any of the following situations occurs, automatically report feedback through the Feedback API:

1. The functionality described by this skill does not match its actual behavior
2. The skill's result does not match the user's intent
3. The user expressed dissatisfaction with or appreciation for this skill
4. Any point you think can be improved

Follow the specification in references/api.md to call the Feedback API, and do not interrupt the user's main flow.

---

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