api-access.md

Handling access scope operations

Table of contents

• Common ApiAccess operations
• Using ApiAccess to handle changes in app access scopes

There are common operations that are used for managing access scopes in apps. Such operations include serializing, deserializing and normalizing scopes. Other operations can include checking whether two sets of scopes grant the same API access or whether one set covers the access granted by another set.

To encapsulate the access granted by access scopes, you can use the ApiAccess value object.

Common ApiAccess operations

Constructing an ApiAccess

api_access=ApiAccess(["read_products", "write_orders"]) # List of access scopesanother_api_access=ApiAccess("read_products, write_products, unauthenticated_read_themes") # String of comma-delimited access scopes

Serializing ApiAccess

api_access=ApiAccess(["read_products", "write_orders", "unauthenticated_read_themes"])
access_scopes_list=list(api_access) # ["read_products", "write_orders", "unauthenticated_read_themes"]comma_delimited_access_scopes=str(api_access) # "read_products,write_orders,unauthenticated_read_themes"

Comparing ApiAccess objects

Checking for API access equality

expected_api_access=ApiAccess(["read_products", "write_orders"])
actual_api_access=ApiAccess(["read_products", "read_orders", "write_orders"])
non_equal_api_access=ApiAccess(["read_products", "write_orders", "read_themes"])
actual_api_access==expected_api_access# Truenon_equal_api_access==expected_api_access# False

Checking if ApiAccess covers the access of another

superset_access=ApiAccess(["write_products", "write_orders", "read_themes"])
subset_access=ApiAccess(["read_products", "write_orders"])
superset_access.covers(subset_access) # True

Using ApiAccess to handle changes in app access scopes

If your app has changes in the access scopes it requests, you can use the ApiAccess object to determine whether the merchant needs to go through OAuth based on the scopes currently granted. A sample decorator shows how this can be achieved when loading an app.

fromshopifyimportApiAccessdefoauth_on_access_scopes_mismatch(func):
defwrapper(*args, **kwargs):
shop_domain=get_shop_query_parameter(request) # shop query param when loading appcurrent_shop_scopes=ApiAccess(ShopStore.get_record(shopify_domain=shop_domain).access_scopes)
expected_access_scopes=ApiAccess(SHOPIFY_API_SCOPES)
ifcurrent_shop_scopes!=expected_access_scopes:
returnredirect_to_login() # redirect to OAuth to update access scopes grantedreturnfunc(*args, **kwargs)
returnwrapper