docs.
md 1/26/2022
Shopline Storefront OAuth
This doc assumes you already have basic understanding of OAuth2 framework. For more information about oauth2, you can refer to link.
Creating and querying a Shop OAuth Application
When to use these endpoint?
Merchant Mini App Store Storefront App Admin Panel OpenAPI
Enable Storefront App
Login
Store developer oauth refresh token and oauth token
Export mobile app package (ipa / apk)
Create store oauth application if not exist
Store OAuth Client ID + Secrets
Create Mobile app package with client id, secret and redirect uri
IPA / APK packages
Merchant Mini App Store Storefront App Admin Panel OpenAPI
This part is currently in developement
The scope of a token may required running manual script to grant
For creating shop oauth application, you need to create it through open-api
Get OAuth Applications
scope: store_oauth_applications
grants: create
GET /v1/store_oauth_applications
Header
Field Type Description
Bearer authenication with access token, example: Bearer
Authorization String
eyJhbGciOiJIUzI1NiJ9.eyJqdGkiOiJkYWUyZGU4YmMzMDQxOTFlODdjN2MwZDQ2ZTc4OWE0NiIsImRhdGEiOnsidXNlcl9pZCI6IjYxZ
Response
Field Type Description
items Array of application List of application for this merchant
1/5
docs.md 1/26/2022
Application
Field Description
id Application ID
app_id App UID
app_secret App Secret
Create OAuth Application
scope: store_oauth_applications
grants: create
POST /v1/store_oauth_applications
Request
Field Type Description
redirect_uri String Redirect Uri
is_redirect_to_simplified_login boolean Is simplifed login ui, default is true
Response
Field Description
id Application ID
app_id App UID
app_secret App Secret
Authorization Token
Autorization URI & Query Parameters
The endpoint to access shop-oauth is always storefront host. Same for merchant with custom domain.
Example:
https://hung190.shoplineapp.com/oauth/authorize?client_id={masked}&response_type=code&redirect_uri=https%3A%2F%2my-
awesome-app.shoplineapp.com%2Foauth_callback&scope=shop
Params Type Description
client_id String Client ID for OAuth Application, you should create shop OAuth Application with OpenAPI
client_secret String Client secret for OAuth Application, you should create shop OAuth Application with OpenAPI
Your redirect_uri should be whitelisted when create oauth application. If the redirect_uri is not whitelisted, you will encounter
redirect_uri String
error in the OAuth flow.
scope String Currently, only have one scope shop
repsonse_type String This should always be code
Token Exchange
After users has authorized your app, our authorization server will redirect user back to your redirect_uri with the authorization code. The following is a dummy
uri to illustrate this idea.
https://my-awesome-app.shoplineapp.com/oauth_callback?code=69a801d873305eca0245ef951687c491bf81a79421b10a4f42743b1ff3e85da0
You should then use code to exchange user's access token from us in your backend server. The following curl example illustrates how to exchange user's access
token with code
curl -d '{"code":"69a801d873305eca0245ef951687c491bf81a79421b10a4f42743b1ff3e85da0",
"grant_type":"authorization_code", "client_id": "your_client_id", "client_secret": "your_client_secret",
"redirect_uri": "redirect_uri"}' -H "Content-Type: application/json" -X POST
https://hung190.shoplineapp.com/oauth/token
Refresh Token
2/5
docs.md 1/26/2022
You can find expires_in and refresh_token in the payload when you receive access token from shop oauth. expires_in means the token will expire after x
seconds.
When the token is close to expire time, you can use refresh_token to exchange for a new token. Here is an example to refresh access token with refresh_token
POST https://hung190.shoplineapp.com/oauth/token?
grant_type=refresh_token
client_id={client id}&
client_secret={client secret}&
refresh_token={refresh token}&
redirect_uri={redirect uri}
Params Type Description
client_id String Client ID for OAuth Application, you should create shop OAuth Application with OpenAPI
client_secret String Client secret for OAuth Application, you should create shop OAuth Application with OpenAPI
Your redirect_uri should be whitelisted when create oauth application. If the redirect_uri is not whitelisted, you will encounter
redirect_uri String
error in the OAuth flow.
refresh_token String refresh_token when we exchange token from shop oauth
grant_type String This should always be refresh_token
Token Info
For fetching detail information for shop oauth access token (like merchant id, customer id), you can use token info endpoint
GET {storefront host}/oauth/token/info
Header
Field Type Description
Bearer authenication with access token, example: Bearer
Authorization String
eyJhbGciOiJIUzI1NiJ9.eyJqdGkiOiJkYWUyZGU4YmMzMDQxOTFlODdjN2MwZDQ2ZTc4OWE0NiIsImRhdGEiOnsidXNlcl9pZCI6IjYxZ
Errors
HTTP Status Code Error Code Description
401 MISSING_TOKEN_ERROR Token is required in the header
401 TOKEN_EXPIRED Token is expired, you may need to get a new by refresh token
401 TOKEN_REVOKED Token is revoked, you may need to get a new one by authorization
Response
mobile_phone, country_calling_code are still in development
{
"resource_owner_id": "61e7770bbc52705cb1b94e0e",
"scope": [
"shop"
],
"expires_in": 15689115,
"application": {
"uid": "ba9cae4b63616846d49802e6a67918dcab446e3b3c1473ba142eaba35938379c"
},
"created_at": 1642585915,
"user": {
"_id": "61e7770bbc52705cb1b94e0e",
"email": "hung+1223test@shoplineapp.com",
"mobile_phone": "{{user-phone}}",
"country_calling_code": "{{country_calling_code}}",
"locale_code": "en",
"name": "Yeung Yiu Hung"
},
"merchant": {
"_id": "61e775b1857feb0037c6500c",
"email": "hung+phonelogin@shoplineapp.com",
"handle": "hungphonelogin530",
"name": "Hung Test Store (Phone Login)"
}
}
3/5
docs.md 1/26/2022
Complete Flow
OAuth Client Storefront Host Storefront SSO
GET /api/users/current + cookies
current session user id
check and validate token with current user id and merchant id
par [if valid token found]
POST /oauth/token + refresh token
Return token + refresh token
Update token to token storage
Redirect end user to next step
[if no valid token found]
GET /oauth/authorize (client_id, merchant_id, scope)
No user session available (unauthenticated)
Redirect end user to Storefront login page
Authenticates user with credentials
Redirect end user to next step
Check end user permission to grant application access
Redirect to redirect_uri with authorization code by query string
par [Exchange token with authorization code]
POST /oauth/token + authorization code
Return token and refresh token
GET /oauth/token/info
Return token info
Save token info to token storage
OAuth Client Storefront Host Storefront SSO
4/5
docs.md 1/26/2022
5/5
