Authentication

If your application needs to access a Cloud user's business data — such as product or order information — via the ZhenHub Open Platform, it must first obtain an access token through user authorization.

To do this, you need to guide the seller through the "Login with Cloud account and authorize application" process. This process follows the OAuth 2.0 international standard protocol for secure user authentication and authorization.

Constructing an Authorization Link

To initiate the OAuth 2.0 authorization flow, construct the authorization URL using the following format:

Test Environment Authorization URL:

Production Environment Authorization URL:

Note: Replace the values in curly brackets ({}) with the actual parameters from your application. For example, {client_id} should be replaced with your registered application's client ID.

Parameter information:

Parameter	Required?	Example Value	Description
client_id	Yes	zhenhub_h***********Whw	The Client Key of your application, assigned by ZhenHub Open Platform.
redirect_uri	Yes	https://yourapp.com/callback	The redirect URI provided during app creation. This must exactly match the one registered in your application settings.
response_type	Yes	code	The type of response expected. For authorization code flow, the value must be code.
state	Yes	Your secure random string.	The state parameter must be non-empty and should be a single-use token generated specifically for a given request. It is important that the state parameter is impossible to guess, associated with a specific request, and used once. Use state for CSRF protection.
scope	Yes	Inbound.Write, Order.Write, Product.Write, Inbound.Read, Order.Read, Product.Read, Calculator	A comma-separated list of scopes (permissions) the application requests. Example: Inbound.Write,Order.Write,Product.Read.

User Authorization

When you open the authorization link in a browser, you will be prompted to enter your account credentials. After logging in, the authorization screen will be displayed. If you do not have a Cloud account, you can use a test account provided in the testing tool to simulate the login process. Once logged in with the test account, re-open the authorization link to directly access the authorization interface.

Receiving the Authorization Code

Once the user completes the authorization process, the ZhenHub Open Platform will redirect to your specified callback URL with an authorization code. Your application should then use this code to request an access token.

Note: The authorization code is valid for five minutes and can be used only once. Once it expires, you will need to restart the authorization process to obtain a new code.

Get Token Using Authorization Code

Use the authorization code to obtain an access token.

Test environment: POST

Production environment: POST

Body

Parameter	Required?	Example Value	Description
client_id	Yes	zhenhub_********8stM	The Client Key of your application.
redirect_uri	Yes	Your app's redirect URI.	The redirect URI provided during app creation. This must exactly match the one registered in your application settings.
response_type	Yes	code	The type of authorization being requested. Use the fixed value "code".
scope	Yes	Inbound.Write, Order.Write, Product.Write, Inbound.Read, Order.Read, Product.Read, Calculator	The permissions your application is requesting. Multiple scopes are separated by commas.
code	Yes	********T0zz	The authorization code returned to the callback URL after the user authorizes the app.
client_secret	Yes	********hG66	The client secret associated with your application.

{
   "client_id": "zhenhub_********8stM",
   "response_type": "code",
   "redirect_uri": "https://*****.com",
   "scope": "Inbound.Write,Order.Write,Product.Write,Inbound.Read,Order.Read,Product.Read,Calculator",
   "code": "********T0zz",
   "client_secret": "********hG66"
}

Response

Parameter	Example Value	Description
access_token	zhenhub_********d4TB	The access token returned by the server. Use this token to access ZhenHub Open API resources.
expires_in	7199 | -1	The token's validity period in seconds. -1 indicates that the token does not expire.
client_id	zhenhub_h***********Whw	The Client Key of your application.
scope	Inbound.Write, Order.Write, Product.Write, Inbound.Read, Order.Read, Product.Read, Calculator	The list of scopes (permissions) granted for this access token.
openid	6469735808173060	The unique identifier of the authorized user.

Using Access Token

Include your Access-Token and Client-Id in the request headers when calling any ZhenHub API.

Header

{
   "Client-Id": "zhenhub_********8stM",
   "X-Access-Token": "YOUR_AUTHORIZATION"
}