--- title: "App authorization" doc_type: static doc_category: static doc_version: v20270301 source_url: html: 'https://developer.shopline.com/docs/apps/api-instructions-for-use/app-authorization' md: 'https://developer.shopline.com/docs/apps/api-instructions-for-use/app-authorization.md' --- # App authorization Public apps and custom apps must go through app authorization to obtain an access token. This token, acquired via [OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc6749), allows you to access a merchant's store data through SHOPLINE's [Admin REST APIs](https://developer.shopline.com/docs/admin-rest-api/access/storefront-api/create-an-access-token.md?lang=en) and [Admin GraphQL APIs](https://developer.shopline.com/docs/admin-graph-ql-api/schema-documentation.md?lang=en). --- ## Workflow The following workflow shows the app authorization process among a merchant, an app, and SHOPLINE.
![应用授权英文图-图1应用授权流程图.png](https://s2cdn.myshopline.com/slfs/op-new/171644800471330/应用授权英文图-图1应用授权流程图.png)
Figure 1. App authorization workflow
--- ## Prerequisites{#prerequisites} To seamlessly complete the app authorization process, ensure that: - You have a [SHOPLINE Partner Portal](https://developer.myshopline.com) account. - Your app is a [public app](https://developer.shopline.com/docs/apps/application-management/creating-an-app.md#creating-a-public-app) or [custom app](https://developer.shopline.com/docs/apps/application-management/creating-an-app.md#creating-a-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 Partner Portal](https://developer.myshopline.com). 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{#step1} 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}×tamp={timestamp}&sign={sign} ``` The request carries the following query parameters: | **Query parameter** | **Description** | | --- | --- | | appkey | The unique identifier for the app. | | handle | The store's unique identifier, which is the first part of the store's domain name. For example, if a store's domain name is `open001.myshopline.com`, the store handle is `open001`. | | timestamp | The timestamp, in milliseconds, indicates when the request was sent. | | sign | The signature of the request, which is used to verify the request's authenticity. Refer to [Generate and verify signatures](https://developer.shopline.com/docs/apps/api-instructions-for-use/generate-and-verify-signatures.md?lang=en) for more details about request signatures. | If your app is an embedded app, the request also includes the following query parameter. > **note** > > An embedded app is an app integrated into the SHOPLINE Admin. This app mode is configured in the SHOPLINE Partner Portal during app creation. > > > ![image7.png](https://s2cdn.myshopline.com/slfs/op-new/171630524140697/image7.png) | **Query parameter** | **Description** | | --- | --- | | lang | The store language that the merchant sets in the SHOPLINE Admin. Valid values are:
  • `zh-hans-cn`: Simplified Chinese
  • `zh-hant-tw`: Traditional Chinese
  • `en`: English
  • `ms`: Malay
  • `vi`: Vietnamese
  • `th`: Thai
  • `id`: Indonesian
  • `ja`: Japanese
    • | 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](https://developer.shopline.com/docs/apps/api-instructions-for-use/generate-and-verify-signatures.md?lang=en). ![应用授权英文图-应用安装验证流程.jpg](https://s2cdn.myshopline.com/slfs/op-new/171879459633834/应用授权英文图-应用安装验证流程.jpg)
    Figure 2. App installation verification workflow
    ### Step 2: Request an authorization code{#step2} 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. > **note** > > If the merchant has authorized your app and the data access scope does not change, SHOPLINE will not display the authorization page even if you make an authorization request. Redirect the merchant to the following URL or provide the following URL to the merchant: ```html 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: | **Domain parameter** | **Description** | | --- | --- | | handle | The store's unique identifier, which is the first part of the store's domain name. For example, if a store's domain name is `open001.myshopline.com`, the store handle is `open001`. Obtain the handle value from SHOPLINE's request in [Step 1](#step1). | | **Query parameter** | **Description** | | appKey | The unique identifier for the app, used to tell SHOPLINE that the merchant intends to install this app. Refer to [Prerequisites](#prerequisites) for how to obtain the app key. | | responseType | The authorization method. The value is `code`, which means that the [OAuth 2.0 authorization code grant](https://datatracker.ietf.org/doc/html/rfc6749#section-4.1) flow is used. | | scope | The scope of access to store resources, represented by [permission points](https://developer.shopline.com/docs/apps/api-instructions-for-use/access-scope.md). If you apply for multiple permissions, use commas to separate permission points, such as `read_products,read_orders`. | | redirectUri | The URL that SHOPLINE redirects to after the merchant authorizes the app. This URL must be identical to one of the App callback URLs that you specify in the SHOPLINE Partner Portal and must be URL encoded. | You can also include the following query parameter: | **Query parameter** | **Description** | | --- | --- | | customField | A custom field, which will be passed through to `redirectUri` during the callback. The value of this parameter must be URL encoded. | When you redirect the merchant to SHOPLINE, SHOPLINE will first authenticate the merchant's identity. The merchant must log in to the [SHOPLINE Admin](https://smilesmileshop.myshopline.com/admin/) before being redirected to the authorization page. ### Step 3: Receive the authorization code{#step3} After the merchant authorizes your app's access scope, SHOPLINE redirects the merchant to `redirectUri` that you pass through the [authorization code request](#step2). ```html GET https://{redirectUri}?appkey={appkey}&code={code}&customField={customField}&handle={handle}×tamp={timestamp}&sign={sign} ``` The request carries the following query parameters. | **Query parameter** | **Description** | | --- | --- | | appkey | The unique identifier for the app. | | code | The authorization code granted through OAuth 2.0, which expires in ten minutes. | | customField | A custom field, which is returned if you pass it in [Step 2. ](#step2) | | handle | The store's unique identifier, which is the first part of the store's domain name. For example, if a store's domain name is `open001.myshopline.com`, the store handle is `open001`. | | timestamp | The timestamp, in milliseconds, indicates when the request was sent. | | sign | The signature of the request, which is used to verify the request's authenticity. Refer to [Generate and verify signatures](https://developer.shopline.com/docs/apps/api-instructions-for-use/generate-and-verify-signatures.md?lang=en) for more details about request signatures. | If your app is an embedded app within the SHOPLINE Admin, the request also includes the following query parameter. | **Query parameter** | **Description** | | --- | --- | | lang | The store language that the merchant sets in the SHOPLINE Admin. Valid values are:
  • `zh-hans-cn`: Simplified Chinese
  • `zh-hant-tw`: Traditional Chinese
  • `en`: English
  • `ms`: Malay
  • `vi`: Vietnamese
  • `th`: Thai
  • `id`: Indonesian
  • `ja`: Japanese
    • | After receiving the request from SHOPLINE, [verify the signature](https://developer.shopline.com/docs/apps/api-instructions-for-use/generate-and-verify-signatures.md?lang=en) 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](#step3). ```html 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: | **Domain parameter** | **Description** | | --- | --- | | handle | The store's unique identifier, which is the first part of the store's domain name. For example, if a store's domain name is `open001.myshopline.com`, the store handle is `open001`. | | **Header parameter** | **Description** | | Content-type | The value of this parameter is fixed to `App/json`. | | appkey | The unique identifier for the app. | | timestamp | The timestamp, in milliseconds, indicates when the request was sent. | | sign | The signature of the request, which is used to verify the request's authenticity. Refer to [Generate and verify signatures](https://developer.shopline.com/docs/apps/api-instructions-for-use/generate-and-verify-signatures.md?lang=en) for more details about request signatures. | | **Body parameter** | **Description** | | code | The authorization code granted through OAuth 2.0, which expires in ten minutes. | > **note** > > SHOPLINE has rate limits for this access token request API. Apps must not repeatedly request access tokens for the same store in a short period. Additionally, avoid refreshing the access token immediately after obtaining it. ### Step 5: Receive the access token After receiving your access token request, SHOPLINE first [verifies the signature](https://developer.shopline.com/docs/apps/api-instructions-for-use/generate-and-verify-signatures.md?lang=en) 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} }, "traceId":{traceId} } ``` The response includes the following parameters: | > | **Parameter** | **Description** | | --- | --- | --- | | > |code| The HTTP status code. Valid values are:
  • `200`: indicates that the request succeeded.
  • `500`: indicates that the request failed.
    • | | > | i18nCode | The error code, returned together with the HTTP status code `500`. See [Error codes](#step5errorcode) for details on specific values. | | > | message | The error message for `i18nCode`. | | data | accessToken | The access token, used to access store resources through Admin APIs. The token expired in ten hours. To maintain validity, refresh the token before expiration by following [Step 6](#step6). | | ^ | expireTime | The expiration date and time of the access token, in UTC format: `yyyy-MM-dd'T'HH:mm:ss.SSSXXX`, such as `2023-11-10T16:37:48.178+00:00`. | | ^ | scope | The scope of access to store resources, represented by [permission points](https://developer.shopline.com/docs/apps/api-instructions-for-use/access-scope.md). If you apply for multiple permissions, use commas to separate permission points, such as `read_products,read_orders`. | | > | traceId | A globally unique identifier for the request. It is used to track the request flow throughout the system, allowing for easy location and debugging when issues arise. | #### Error codes{#step5errorcode} HTTP status code: `500` | **Error code** | **Description** | | --- | --- | | REQUEST_FREQUENTLY | The request exceeds the rate limit. Try again later. | | OAUTH_CODE_INVALID | The authorization code you use expires. Obtain a new authorization code. | | STORE_INFORMATION_ERROR | The store is currently unavailable. Try again later. | | REQUEST_NOT_IN_APP_IP_WHITELIST | Your app's IP address is not on the whitelist. Verify that you have entered the correct IP address in the SHOPLINE Partner Portal. | | TOKEN_CREATE_EXCEPTION | Fail to create an access token. Try again later. | ### Step 6: Refresh the access token{#step6} 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. ```html 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: | **Domain parameter** | **Description** | | --- | --- | | handle | The store's unique identifier, which is the first part of the store's domain name. For example, if a store's domain name is `open001.myshopline.com`, the store handle is `open001`. | | **Header parameter** | **Description** | | Content-type | The value of this parameter is fixed to `App/json`. | | appkey | The unique identifier for the app. | | timestamp | The timestamp, in milliseconds, indicates when the request was sent. | | sign | The signature of the request, which is used to verify the request's authenticity. Refer to [Generate and verify signatures](https://developer.shopline.com/docs/apps/api-instructions-for-use/generate-and-verify-signatures.md?lang=en) for more details about request signatures. | > **note** > > SHOPLINE has rate limits for this access token refresh API. Apps must not repeatedly request access tokens for the same store in a short period. ### Step 7: Receive the refresh access token After receiving your refresh token request, SHOPLINE first [verifies the signature](https://developer.shopline.com/docs/apps/api-instructions-for-use/generate-and-verify-signatures.md?lang=en) you passed in. If the verification is successful, SHOPLINE returns the following response in JSON. ```html { "code": 200, "i18nCode": "SUCCESS", "message": null, "data": { "accessToken": {accessToken}, "expireTime": {expireTime}, "scope": {scope} }, "traceId":{traceId} } ``` The response includes the following parameters: | > | **Parameter** | **Description** | | --- | --- | --- | | > | code | The HTTP status code. Valid values are:
  • `200`: indicates that the request succeeded.
  • `500`: indicates that the request failed.
    • | | > | i18nCode | The error code, returned together with the HTTP status code `500`. See [Error codes](#step7errorcode) for details on specific values. | | > | message | The error message for `i18nCode`. | | data | accessToken | The access token, used to access store resources through Admin APIs. The token expired in ten hours. To maintain validity, refresh the token before expiration by following [Step 6](#step6). | | ^ | expireTime | The expiration date and time of the access token, in UTC format: `yyyy-MM-dd'T'HH:mm:ss.SSSXXX`, such as `2023-11-10T16:37:48.178+00:00`. | | ^ | scope | The scope of access to store resources, represented by [permission points](https://developer.shopline.com/docs/apps/api-instructions-for-use/access-scope.md). If you apply for multiple permissions, use commas to separate permission points, such as `read_products,read_orders`. | | > | traceId | A globally unique identifier for the request. It is used to track the request flow throughout the system, allowing for easy location and debugging when issues arise. | #### Error codes{#step7errorcode} HTTP status code: `500` | **Error code** | **Description** | | --- | --- | | REQUEST_FREQUENTLY | The request exceeds the rate limit. Try again later. | | STORE_NOT_INSTALL_APP | The store does not install your app. | | APP_AUDIT_NOT_PASS | Your app did not pass the audit. Resubmit for review in the SHOPLINE Partner Portal. | | REQUEST_NOT_IN_APP_IP_WHITELIST | Your app's IP address is not on the whitelist. Verify that you have entered the correct IP address in the SHOPLINE Partner Portal. | | TOKEN_CREATE_EXCEPTION | Fail to create an access token. Try again later. | ### 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](#step2). For apps embedded in SHOPLINE Admin, use the [Redirect](https://developer.shopline.com/docs/apps/development-tool/app-bridge/actions/routing.md) method of [App Bridge](https://developer.shopline.com/docs/apps/development-tool/app-bridge/overview.md) for this redirection.