App authorization​

Public apps and custom apps must go through app authorization to obtain an access token. This token, acquired via OAuth 2.0, allows you to access a merchant's store data through SHOPLINE's Admin REST APIs and Admin GraphQL APIs.

Workflow​

The following workflow shows the app authorization process among a merchant, an app, and SHOPLINE.

Prerequisites​

To seamlessly complete the app authorization process, ensure that:

• You have a SHOPLINE Developer Center account.
• Your app is a public app or custom app.
• Get the app key, which is used to authenticate your app during API requests.
• Get the app secret, which is used to generate and verify request signatures.

To get the app key and app secret, follow the steps:

1. Log in to the SHOPLINE Developer Center.
2. Go to Apps.
3. Click the target app name, and you will find the app key and app secret under App credentials.

Authorization procedure​

Step 1 Verify the app installation request​

When a merchant installs your app, SHOPLINE sends the following request to your app's URL.

GET https://{appUrl}?appkey={appkey}&handle={handle}&lang={lang}&timestamp={timestamp}&sign={sign}

The request carries the following query parameters:

If your app is an embedded app, the request also includes the following query parameter.

After receiving the request from SHOPLINE, follow the workflow in Figure 2 for your next steps. For more information about how to verify the signature, refer to Verify the signature of a GET request.

Step 2: Request an authorization code​

When you confirm that the merchant needs to authorize your app:

• for public apps, redirect the merchant to SHOPLINE and load the authorization page in the merchant's browser.
• for custom apps, provide the merchant with the OAuth authorization URL to be accessed in their web browser.

The authorization page shows the data access scope that the app needs.

Redirect the merchant to the following URL or provide the following URL to the merchant:

GET https://{handle}.myshopline.com/admin/oauth-web/#/oauth/authorize?appKey={appKey}&responseType=code&scope={scope}&redirectUri={redirectUri}

The request must include the following parameters:

You can also include the following query parameter:

When you redirect the merchant to SHOPLINE, SHOPLINE will first authenticate the merchant's identity. The merchant must log in to the SHOPLINE Admin before being redirected to the authorization page.

Step 3: Receive the authorization code​

After the merchant authorizes your app's access scope, SHOPLINE redirects the merchant to redirectUri that you pass through the authorization code request.

GET https://{redirectUri}?appkey={appkey}&code={code}&customField={customField}&handle={handle}&timestamp={timestamp}&sign={sign}

The request carries the following query parameters.

If your app is an embedded app within the SHOPLINE Admin, the request also includes the following query parameter.

After receiving the request from SHOPLINE, verify the signature first. If the verification is successful, obtain the authorization code through the code parameter. The authorization code is used for requesting an access token in the next step.

Step 4: Request an access token​

To request an access token for a merchant's store, send the following request using the authorization code obtained from Step 3.

POST    https://{handle}.myshopline.com/admin/oauth/token/create
Header  Content-type: application/json
            appkey: {appkey}
            timestamp: {timestamp}
            sign: {sign}
Body     {"code":{code}}

The request must include the following parameters:

Step 5: Receive the access token​

After receiving your access token request, SHOPLINE first verifies the signature you passed in. If the verification is successful, SHOPLINE returns the following response in JSON.

{
	"code": 200,
	"i18nCode": "SUCCESS",
	"message": null,
	"data": {
		"accessToken": {accessToken},
		"expireTime": {expireTime},
		"scope": {scope}
	}
}

The response includes the following parameters:

Error codes​

HTTP status code: 500

Step 6: Refresh the access token​

To ensure the security of merchant data, the access token has a validity period of 10 hours. If the merchant installs your app, you must refresh the access token by calling the following API before it expires.

POST    https://{handle}.myshopline.com/admin/oauth/token/refresh
Header  Content-type: application/json
            appkey: {appkey}
            timestamp: {timestamp}
            sign: {sign}

The request must include the following parameters:

Step 7: Receive the refresh access token​

After receiving your refresh token request, SHOPLINE first verifies the signature you passed in. If the verification is successful, SHOPLINE returns the following response in JSON.

{
	"code": 200,
	"i18nCode": "SUCCESS",
	"message": null,
	"data": {
		"accessToken": {accessToken},
		"expireTime": {expireTime},
		"scope": {scope}
	}
}

The response includes the following parameters:

Error codes​

HTTP status code: 500

Step 8: Request additional permission scope (optional)​

When you release an update for your app that requires new permissions, merchants who have already installed your app need to grant these additional permissions. For example, if your app initially had access only to read_products but needs read_orders due to the update, you must modify the requested permission scope. To update the permission scope, redirect the merchant to the authorization page to obtain a new authorization code. For apps embedded in SHOPLINE Admin, use the Redirect method of App Bridge for this redirection.