TUTORIAL FOR USE SCOPE

1. SCOPE HARAWEB

1.1 Scope

- These are scopes in “Haraweb” of https://developers.haravan.com

- 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.

1.2 API List for haraweb scope

- Corresponding to the scope will be the access to the corresponding api.

- The write scope will include read permissions and use the methods: GET, POST, PUT, DELETE.

- The Read scope only uses the GET method.

- API prefix: https://apis.haravan.com/web

- Call the api with the syntax: https://apis.haravan.com/web/{api} .
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://developers.haravan.com

- 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

2.2 API List for commerce scope

- Corresponding to the scope will be the access to the corresponding api.

- The write scope will include read permissions and use the methods: GET, POST, PUT, DELETE.

- The Read scope only uses the GET method

- API prefix: https://apis.haravan.com/com

- Call the api with the syntax: https://apis.haravan.com/com/{api}.
EX: Call API products: https://apis.haravan.com/com/products.json (GET).

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://developers.haravan.com before using this scope.

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

5. SCOPE INSTALL

- These are the scopes used to install the application.

- These are the scopes include:

+ Required scopes.

+ Scope use webhook (optional)

+ Scopes are selected at haraweb and commerece

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 authorize 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:

• Here only describes how the scope works
• Refer to the link below for more information :
  • https://docs.haravan.com/blogs/omni/create-app-and-connect-api

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 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 authorize 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 Option 2: Use scope login and scope install to install the app
(Recommended)

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, increased 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.

- The appliation only use scopes in haraweb, use this API:
https://apis.haravan.com/web/shop.json

- The appliation only use scopes in commerce, use this API
https://apis.haravan.com/com/shop.json

- Note: If you use both the scope in haraweb and commerce, you can use one of the APIs above.

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 seller
• User authorization on Application (configured on the application)

- Before the user starts the application, 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 starts the application.
• If the user isn’t the shop owner (role doesn’t contain ‘admin’), We have 3 cases:
  • Case 1: authorization on seller of the user’s account do 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.