Amazon Store Authorization and Management

This skill is responsible for OAuth authorization of Amazon seller stores, authorized store list management, access token acquisition and refresh, and is a prerequisite for all downstream operations such as report pulling, inventory query, order synchronization, etc.

📌 Related skill: If the user needs to pull Amazon store reports (inventory / order / sales / financial reports, etc.), please switch to
linkfox-amazon-store-report
. This 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 OAuth 2.0 authorization process and token lifecycle management:

Authorization Process: Generate authorization URL → User completes authorization on Amazon → Amazon calls back with authorization code → System exchanges authorization code for tokens → Tokens are securely stored.

Store Name (
sellerName
) is Required: Before calling

/spApi/authorizeUrl

, you must ask the user for a clear, non-empty store name. It is used to mark the account in the "Authorized Stores List"; do not leave it blank or use an empty string.

Token Lifecycle:

accessToken

usually expires in 1 hour;

refreshToken

is used to renew a new

accessToken

without re-authorization.

Data Fields

Authorization URL Response

Field	Type	Description
authorizeUrl	string	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	Market region code NA / EU / FE

Store Tokens

Field	Type	Description
accessToken	string	Credential for calling Amazon open APIs
refreshToken	string	Used to renew accessToken
expiresIn	integer	Expiration time of accessToken in seconds
tokenType	string	Usually "bearer"

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. Use NA if the user does not specify a region.

API Usage

This skill calls store authorization-related interfaces via the LinkFox gateway. For details, see

references/api.md

Available Scripts

```
scripts/authorize_url.py
```
— Generate authorization URL for new stores (
```
sellerName
```
is required)
```
scripts/authorized_stores.py
```
— List all authorized stores
```
scripts/refresh_token.py
```
— Refresh access token for a specific store
```
scripts/store_tokens.py
```
— Query access token for a specific store (for downstream skills)

Usage Scenarios

Scenario 1: Authorize New Store

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

Steps:

Ask for store name
sellerName
(if not provided by the user).
```
/spApi/authorizeUrl
```
requires
```
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 Seller Central.
Call
```
/spApi/authorizeUrl
```
with
```
region
```
and
```
sellerName
```
Provide the returned
```
authorizeUrl
```
to the user and ask them to open it in a browser
User completes authorization on Amazon → Amazon calls back to the system → The system automatically saves the authorization
Optional: Call
```
/spApi/authorizedStores
```
to confirm successful authorization

Scenario 2: View Authorized Stores

User request: "List my authorized Amazon stores"

Steps:

Call
```
/spApi/authorizedStores
```
Display the store list (sellerName / sellerId / region)
Sort by sellerId and region

Scenario 3: Refresh Expired Token

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

Steps:

Call
```
/spApi/refreshToken
```
with
```
sellerId
```
(optional
```
region
```
)
Return the new
```
accessToken
```
/
```
refreshToken
```
The database automatically updates the token information

Scenario 4: Query Store Tokens

User request: "Get the access token for store A123 in the North America region"

Steps:

Call
```
/spApi/storeTokens
```
with
```
sellerId
```
and
```
region
```
Return all token information (for downstream business calls)

Scenario 5: Prepare Tokens for Any Store Operation (Standard Preparation Workflow)

When the user makes any request involving seller backend data (pulling reports, querying inventory, checking orders, etc.), this skill is responsible for the pre-workflow of "select store → get token", and the specific business is handled by the corresponding downstream skill.

Steps:

List authorized stores: Call
```
/spApi/authorizedStores
```
Ask the user to select a store: If there are multiple stores, ask the user to specify which one to use
Get the token for the selected store: Call
```
/spApi/storeTokens
```
with the
```
sellerId
```
and
```
region
```
of the selected store
Pass the
accessToken
to the downstream skill (e.g.,
```
linkfox-amazon-store-report
```
) to perform the specific operation

Why this workflow is critical:

Users may have authorized multiple stores in different regions at the same time
Tokens and permissions for each store are independent of each other
Calls must use tokens matching the store; skipping the "select store" step will lead to ambiguity and errors

Display Rules

Get store name before generating authorization link: If the user does not provide
```
sellerName
```
, you must ask for it first; do not call
```
/spApi/authorizeUrl
```
with an empty value.
Only present data: Display authorization results, store lists, and token information only; do not provide business suggestions.
Security awareness: Do not display the full
```
accessToken
```
/
```
refreshToken
```
in plain text; only show masked forms such as the first 10 characters.
Clear guidance: When returning the authorization link, clearly inform the user to open it in a browser and complete the authorization.
Error explanation: When authorization fails, explain the reason based on the error code and provide suggestions.
Success confirmation: Confirm with the user after authorization is completed, and optionally display basic information of the store.

Important Limitations

sellerName is required:
```
/spApi/authorizeUrl
```
must receive a non-empty
```
sellerName
```
; scripts and agents must verify this before calling.
Token validity period:
```
accessToken
```
expires in 1 hour and needs to be refreshed in a timely manner.
Region-specific: Each store authorization is bound to a specific region; separate authorization is required for different regions.
User isolation: Users can only view/manage stores they have authorized themselves.
Callback whitelist: The system callback URL must be added to the whitelist of the authorization 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 has expired" / "My token expired"	Refresh token
"Get access token for store XXX" / "Get access token for store"	Query store token
"Connect my Amazon seller account" / "Connect my Amazon seller account"	New store authorization

Not applicable — Business beyond the scope of this skill:

Pull Amazon reports → Please use
```
linkfox-amazon-store-report
```
Product listing management, order processing, inventory management, advertising → Handled by other skills

Boundary judgment:

This skill is only responsible for "authorization + store management + token management + preparing accessToken for downstream".
When the user wants to perform specific seller backend operations (such as pulling reports):
1. This skill executes the standard pre-workflow in Scenario 5
2. Then switch to the corresponding downstream skill to complete the business logic
Do not directly call specific Amazon open APIs bypassing this skill.

Quick Reference

Authorization & Token Management APIs

API	Path	Purpose	Auth Required
Get Authorization URL	/spApi/authorizeUrl	Generate authorization URL (requires sellerName)	✅ Yes
List Authorized Stores	/spApi/authorizedStores	Query user's store list	✅ Yes
Refresh Token	/spApi/refreshToken	Refresh access token	✅ Yes
Query Store Tokens	/spApi/storeTokens	Get token for a specific store (for downstream skills)	✅ Yes

For detailed request parameters, response structures, and error codes, see

references/api.md

. For the complete authorization flow chart, see

references/authorization-flow.md

. For quick start examples, see

references/quick-start.md

Feedback:

Automatically report feedback via the Feedback API when any of the following situations occur:

The function described by this skill does not match the actual behavior
The result of the skill does not match the user's intent
The user expresses dissatisfaction or appreciation for this skill
Any point you think can be improved

Call the Feedback API according to the specifications in

references/api.md

, and do not interrupt the user's main process.

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

linkfox-amazon-store-auth

NPX Install

Tags

SKILL.md Content (Chinese)

Amazon Store Authorization and Management

Core Concepts

Data Fields

Authorization URL Response

Authorized Store Item

Store Tokens

Supported Regions

API Usage

Available Scripts

Usage Scenarios

Scenario 1: Authorize New Store

Scenario 2: View Authorized Stores

Scenario 3: Refresh Expired Token

Scenario 4: Query Store Tokens

Scenario 5: Prepare Tokens for Any Store Operation (Standard Preparation Workflow)

Display Rules

Important Limitations

User Expression & Scenario Quick Reference

Quick Reference

Authorization & Token Management APIs