Skip to main content

AccessScope

Version: 1.0

TABLE OF CONTENTS​

1. SCOPE HARAWEB​

1.1 Scope​

  • These are scopes in “Haraweb” of https://partners.haravan.com/apps

  • Once selected here, you must pass the corresponding scopes when you install the application.

  • For the API use at the sales page.

  • The way to declare haraweb scope: web. {scope_name}.

Ex: web.read_script_tags.

access-scope-1

NameScopeAPI
Contentsweb.read_contents
web.write_contents		Blog
Comment
Page
Redirect
Article
Themesweb.read_themes
web.write_themes		Theme
ScriptTagsweb.read_script_tags
web.write_script_tags		ScriptTag

1.2 API List for haraweb scope​

EX: Call API get scriptTags: https://apis.haravan.com/web/script_tags.json (GET).

2. SCOPE COMMERCE​

2.1 Scope​

  • These are scopes in “Commerce” of https://partners.haravan.com/apps

  • Once selected here, you must pass the corresponding scopes when you install the application.

  • For the API use at the admin page.

  • The way to declare commerce scope: com.{scope_name}.

Ex: com.write_products

access-scope-2

2.2 API List for commerce scope​

EX: Call API products: https://apis.haravan.com/com/products.json (GET).

NameScopeAPI
Inventoriescom.read_inventories
com.write_inventories		Inventory adjustment
Inventory transfer
Purchase order
Purchase receive
Inventory location
Shippingscom.read_shippings
com.write_shippings		Carrier service
Customerscom.read_customers
com.write_customers		Customer
Customer address
Productscom.read_products
com.write_products		Product
Smart_collection
Collect
Custom_collections
Product variant
Product Image
Write Orderscom.read_orders
com.write_orders		Order
Transaction

3. SCOPE WEBHOOK​

  • This is a scope to using webhooks for the application. Only shop owner (role contains ‘admin’) can use it.

  • When using webhooks, this scope is required.

  • You need to register webhook on https://partners.haravan.com/apps before using this scope.

ScopeDescription
wh_apiScope use webhook

4. SCOPE LOGIN​

  • These are the required scopes to log in and get user information

  • Also you can add more scope from haraweb and commerce

ScopeDescription
1openid
2profile
3emailGet an email of the login user
4orgGet org information (org_id , org_name)
5userinfoGet information of login user

5. SCOPE INSTALL​

  • These are the scopes used to install the application.

  • These are the scopes include:

    • Required scopes.

      ScopeDescription
      1openid
      2profile
      3emailGet an email of the login user
      4orgGet org information (org_id , org_name)
      5userinfoGet information of login user
      6grant_serviceThis is the scope that only the shop owner (role contains ‘admin’) can use.
      function:
      + Get long-lived access_token
      + Install the application on the Seller application list

    • Scope use webhook (optional)

    • Scopes are selected at haraweb and commerce

6. HOW TO USE SCOPE WHEN INSTALLING THE APP​

  • When installing, you need to focus on the scope login and scope install.

  • As you can see, the scope login and install are mostly the same and both are used to pass to the authorized URL to get the code and id_token. So, depending on how to use the scope, you can install the app in two options.

  • Note:

6.1 Option 1: Use scope login to install the app​

6.1.1 How it works​

  • As mentioned, login and install are both call URL authorize but the different scope is passed (scope login or install).

  • So, we can pass the selected scope at haraweb and commerce with the scope login right from the first call to the authorized URL.

  • You still have the code corresponding to the scope passed, using the OAuth 2 library to render access_token.

6.1.2 Features​

  • call the authorization URL once.

  • This access_token is called access_token user, and it’s short-lived access_token

  • The application can only be used by users who install it.

  • Does not appear on the seller app list.

  • Unable to use webhook.

6.2.1 How it works​

  • First, call the authorization URL with scope login to get id_token.

  • Use JWT to decode this id_token to get an object including user information, role users, shop information.

  • You need to verify the role of the logged-in user:

    • If the user is the shop owner (role contains ‘admin’) then call URL authorize with scope install (because webhook scope and grant_service scope are only used by the shop owner)

    • If the user isn’t the shop owner (role doesn’t contain ‘admin’) then show the error message.

  • You have the code corresponding to the scope passed, using the OAuth 2 library to render access_token.

6.2.2 Features​

  • Can verify user and shop information twice, increase security, and ability to manage users.

  • Access_token is a long-lived access_token.

  • Install the application on the Seller application list.

7. GET SHOP INFORMATION AFTER INSTALLING THE APP.​

8. HOW TO USE SCOPE LOGIN WHEN USING THE APP​

  • When the application was installed, we need to verify that the logged-in user has access to the application

  • There are 2 types of user authorization:

    • User authorization on the seller

    • User authorization on Application (configured on the application)

  • Before the user starts the application, call the authorization URL with scope login to get the id_token

  • Use JWT to decode this id_token to get an object including user information, role users, shop information.

  • You need to verify the role of the logged-in user:

    • If the user is the shop owner (role contains ‘admin’) then start the application.

    • If the user isn’t the shop owner (role doesn’t contain ‘admin’), We have 3 cases:

      • Case 1: authorization on the seller of the user’s account does not accept to use the scope of the application, show messages “you are not authorized to use the application”.

      • Case 2: That user has permission to use the application's scopes but the user is not authorized to use the app (if the application has its own authorization system), show messages “you are not authorized to use the application”.

      • Case 3: That user does not have permission to use the application's scopes, but the user is allowed to use the application (if the application has its own authorization system), starts the application.