Miravia Open Platform
Miravia - Seller authorization
If your application needs to access the business data of Miravia sellers (like product and order information), you need to get the authorization from sellers, that is, the “Access Token” required for accessing the sellers’ data.
You need to guide the sellers to complete the flow of “using Miravia seller account to log in and authorize the application”. This process uses the international OAuth2.0 standard protocol for user authentication and authorization. Miravia Open Platform adopts the “Code for token” mode, described as below.
Authorization steps
Please find the authorization steps below:
Step 1. Concatenate Authorization URL
You will need to generate your 'Authorization URL' in order to trigger the authorization process properly. The Auth URL is consist of 2 key params in order to set up:
- redirect_url: your Callback_URL when creating the app.
- client_id: your App Key which can be found in your app details page.
Sample link for authorization:
https://auth.miravia.com/apps/oauth/authorize?response_type=code&force_auth=true&redirect_uri=https://open.miravia.com/&client_id=500404
For more advanced use of auth url, please find the following table lists the parameters and their description.
| Parameter | Required? | Value | Parameter |
|---|---|---|---|
| client_id | Yes | The App Key of your application, assigned by Lazada Open Platform. | |
| redirect_uri | Yes | The callback URL you provided when creating the application. | The "redirect_uri" is used for receiving the code when a seller completes the authorization. It must be the same with the callback URL you provided when creating the application on Lazada Open Platform. |
| response_type | Yes | code | The authorization type, with the value of "code". |
| force_auth | No | true | Refresh the web browser cookie for a new authorization session. |
| state | No | Customizable, like 1212. | The status of the application; the same for input and response. |
| uuid | No | uuid283118319 | An identity assigned to the seller, which can protect the returned authorization code. |
| country | No | sg,my,th,vn,ph,id,cb | Specify the options of countries that are available in the "Country" drop-down list. For example, specifying "country=sg" means that only "Singapore" is available for choose; specifying "cb" means that the authorization is for "Crossborder" sellers only. Multiple values can be separated by comma. By default, all countries are listed. |
Step 2. Guide sellers to authorize
Guide a seller to open the above authorization URL through the web browser. The following window with the login panel is displayed. The permissions to be granted to the application after the authorization are listed on the left. The seller selects the country, enters seller account and password, and clicks the “Sign in And Authorize” button to complete the authorization of the application
Step 3. Retrieve authorization code
After the seller completes the authorization, Miravia Open Platform will return the authorization code to the callback URL address. Your application can retrieve the code and use it to get the Access Token. The sample authorization code is shown below.
Note: This authorization code will expire within 30 minutes. You need to use this code to get the access token before it expires.
Step 4. Get the access_token
Use the /auth/token/create API to get the Access Token (access_token).
Code sample:
IopClient client = new IopClient(url, appkey, appSecret);
IopRequest request = new IopRequest();
request.setApiName("/auth/token/create");
request.addApiParameter("code", "3_500332_uvxnai9lMwrXRXo36masT39L3");
IopResponse response = client.execute(request);
System.out.println(response.getBody());
Thread.sleep(10);
Step 5. Save the token
The access token will expire in a specific period (expires_in). Before it expires, the seller does not need to authorize the application again. You need to save the latest token properly.
Step 6. Sample of the token
Notes:
1. The “access_token” and “refresh_token” in this sample are for reference only.2. For cross border sellers, the returned access token can be used for multiple sites. Therefore, the “country_user_info” section contains multiple country values.
{ "access_token": "50000300b05h7UYAo1a043ab6xpSZfYn1FKrCtpfahjs8qtTHKdKk3jy0AMPJcM", "country": "es", "refresh_token": "50001301705jA0Yqa1acd3135trFWiAxBNUvFheMk1mtxFeWnTobNw1xtnfOFc9", "account_platform": "seller_center", "refresh_expires_in": 86400, "expires_in": 86400, "code": "0", "request_id": "211b500616576944242451001" }
The following table lists the parameters in the token and their description.
|
Key
|
Type
|
Sample
|
Description
|
|
access_token
|
string
|
50000601c30atpedfgu3LVvik87Ixlsvle3mSoB7701ceb156fPunYZ43GBg
|
Access token.
|
|
refresh_token
|
string
|
500016000300bwa2WteaQyfwBMnPxurcA0mXGhQdTt18356663CfcDTYpWoi
|
Refresh token, used to refresh the token when “refresh_expires_in”>0.
|
|
expires_in
|
number
|
25920 (expires in 25920 seconds)
|
The expiring time of the access token, in seconds. For APPs in "Test" status, the value is 7 days. For APPs in "Online" status, the value is 30 days.
|
|
refresh_expires_in
|
number
|
25920 (expires in 25920 seconds)
|
The expiring time of the refresh token. For APPs in "Test" status, the value is 30 days. For APPs in "Online" status, the value is 180 days.
|
|
country
|
string
|
es
|
The country ID.
|
|
account_id
|
string
|
706388888
|
User ID, which can be ignored when “account_platform” = “seller_center”.
|
|
account
|
string
|
User account.
|
|
|
account_platform
|
string
|
seller_center
|
User platform, supporting multiple platforms.
|
Refresh authorization steps
1. Use “/auth/token/refresh” to refresh the access token
See the following code sample.
IopClient client = new IopClient(url, appkey, appSecret);
IopRequest request = new IopRequest();
request.setApiName("/auth/token/refresh");
request.addApiParameter("refresh_token", "50001600212wcwiOabwyjtEH11acc19aBOvQr9ZYkYDlr987D8BB88LIB8bj");
IopResponse response = client.execute(request);
System.out.println(response.getBody());
Thread.sleep(10);
The returned data structure by “/auth/token/refresh” is the same with that by getting the access token with authorization code. You will get new “access_token” and “refresh_token”. You must save the latest “refresh_token” for getting the new “access_token”. Note that the duration of the access token will be reset, but the duration of the refresh token will not be reset. After the refresh token expires, sellers need to re-authorize your application to generate new access token and refresh token.
Usage notes
- Sellers do not need to authorize again before the token expires.
- If “refresh_expires_in” = 0, the access token cannot be refreshed. Only when “refresh_expires_in” > 0, you can call the /auth/token/refresh API to refresh the access token.
- If token needs to be refreshed, it is recommended to refresh it 30 minutes before the token expires.
