Jushita API guide (Postman)
This topic provides a Postman schema that runs through the Jushita APIs, which helps you complete the integration quickly. If you find a problem during the integration, you can check and correct it against the implementation logic of the APIs in Postman. Use this topic together with IDaaS-Jushita Integration Guide v1.8.4.pdf to understand the business logic more clearly.
Import the schema
Download Jushita.postman_collection.json and import it into Postman:
Open Postman and click Import. In the dialog box that appears, select the File tab and click Upload Files.
Select the downloaded Jushita.postman_collection.json file and click Import to complete the import.
After the import is complete, the folder structure is as follows:
The left sidebar displays the Jushita collection, which contains folders such as Login-related, User Sync-related, and Adaptive 2FA-related, and requests such as Initialize Variables and Get AccessToken.
Add an environment and then switch to it:
Click Add in the environment area in the upper-right corner of Postman to create an environment.
Name the new environment and select it from the environment drop-down list.
The preparations are complete, and you can start testing the APIs. Run the APIs in order. The APIs depend on each other: an API that runs earlier provides the environment variables for the APIs that run later.
Initialize Variables
First, run "Initialize Variables":
The Pre-request Script tab of this request contains an initialization script that automatically sets the host, clientId, clientSecret, username, password, phoneNumber, merchantName, and ivsAppKey environment variables. Click Send to run it.
You can enter any URL. The only purpose is to run the script.
If you have not purchased an instance and need to integrate first, IDaaS can provide a test server for early integration.
The following sections describe how to get the values of these variables.
host
Log on to the IDaaS console and view the Instance Open API Domain Name column in the instance list.
The host is the value of "Instance Open API Domain Name" in the instance list of the IDaaS console. Note that the Jushita version must be idaas-jst-xxx. If it is not, contact IDaaS immediately.
clientId and clientSecret
On the Application List page in the IDaaS console, select the target application. In the API area at the bottom of the page, view the API Key and API Secret.
The API Key is the clientId, and the API Secret is the clientSecret.
username, password, and phoneNumber
The user information here is used to call the API and create an account. You can modify the user information, but it must meet the constraints. If you are prompted that the password policy is not met, adjust the policy in the IDaaS console:
On the Security Settings page in the IDaaS console, find the Password Policy area and adjust the Rule Type and the password complexity requirements as needed.
merchantName
On the Taobao store homepage, view the value of the Store Owner field.
The merchant name is the value of the Store Owner field on the Taobao store homepage. Make sure that you pass the correct value. Otherwise, scoring fails.
A more accurate way is to get the value from the API. See the API documentation:
In the response parameters of the API, find the seller_user_nick field. This value is the merchant name.
If the two values differ, the value from the API prevails.
ivsAppKey
See the API documentation:
On the application management page of Taobao Open Platform, find the App Certificate area and view the App Key.
The ivsAppKey is the App Key on the application management page of Taobao Open Platform. Make sure that you pass the correct value. Otherwise, scoring fails.
Create user flow
Get AccessToken
In Postman, open the Get AccessToken request (POST {{host}}/oauth/token). On the Authorization tab, make sure that the authentication type is Bearer Token, and click Send to send the request.
Get the AccessToken, which provides the token required to authenticate the subsequent APIs:
The Tests tab of this request contains a script that automatically writes the access_token from the response to the accessToken environment variable after the request is sent.
Organization / Query
In Postman, open the Organization/Query request (GET) and click Send to send the request. The Tests script automatically writes the organization ID to an environment variable.
This request queries organizations and adds the last organization to an environment variable. When you create a user, you must set the organization that the user belongs to.
User / Create
In Postman, open the User/Create request (POST). The Body tab contains user information fields such as source, displayName, username, phoneNumber, and password. Click Send to send the request and create the user.
The organization queried in the previous step is used to create the user. After you create the user, enable 2FA for the user in the IDaaS console:
On the Account Management page in the IDaaS console, find the newly created user and turn on the 2FA switch.
SMS 2FA flow
Log on
When you log on, the signature is automatically calculated and the password is encrypted.
After you log on, if 2FA is enabled, the fid environment variable is automatically added.
SMS 2FA - Send Code
The Body of this request contains the fid and authenticatorType fields. Click Send to send the request.
Use the fid returned by logon to send an SMS 2FA verification code.
After the 2FA verification code is sent, the fid is updated.
SMS 2FA - Verify Code
The Body of this request contains the fid, authenticatorType, and code fields.
Use the fid returned in the previous step to verify the SMS 2FA verification code. For code, pass the verification code that you received on your mobile phone. If you do not receive a verification code, check the logs in the IDaaS console to confirm whether the code was sent:
In the left-side navigation pane of the IDaaS console, choose Audit > Operation logs, set Operation Type to SMS, and view the log content to confirm whether the verification code was sent.
OTP binding flow
Log on
Same as above.
OTP - Get Binding QR Code
In Postman, open this request. The Body contains the fid and username fields. Click Send. The response returns the base64QRCode field.
After the retrieval succeeds, the fid environment variable is automatically set.
Use a Base64 image conversion website Base64 Image Conversion Tool to display the OTP binding QR code. Copy the value of base64QRCode and add the prefix data:image/png;base64,.
Paste the concatenated string into the input box of the website. The page generates a QR code image that you can scan.
Use Google Authenticator or another authenticator app to scan the QR code and get the OTP Code.
OTP - Bind
In Postman, open this request. The Body already contains fid and username. Manually enter the value of the otp field.
Enter the OTP Code that you got in the previous step. If the previous step takes too long, the fid expires and you must log on again. After you log on, call "OTP - Get Binding QR Code". Because the binding is already complete, get the OTP Code directly from your authenticator app and call "OTP - Bind".
OTP 2FA flow
Log on
Same as above.
OTP - Verify
The Body of this request contains the fid, secondFactor (set to OTP), and otp fields.
Enter the OTP Code that you got from your authenticator app.