Access tokens

Access tokens are granted by the platform when a merchant agrees to install an app, allowing the app to interact with the platform via REST APIs. Genstore offers two methods to obtain access tokens: Token Exchange and Authorization Code Grant. Token Exchange is recommended for embedded apps, while non-embedded apps should use the Authorization Code Grant method.

Token exchange

Token exchange is based on the OAuth 2.0 Token Exchange Specification and is suitable for embedded apps, which can be facilitated through the App Bridge.

Implement token exchange

1. Session token request: The app requests a session token via an embedded app redirect from the browser.
2. Verification and access token retrieval: The backend verifies the session token and requests a new access token.
3. Using the access token: Genstore verifies and returns the new access token, which the app uses to call APIs.

Token exchange API

Request format:

POST https://{shop}.genmystore.com/oauth2/token

Parameters:

• clientId: App's client ID.
• clientSecret: App's client secret.
• grantType: Authorization type, here as token-exchange.
• subjectToken: Session ID.
• requestedTokenType: The type of token requested, specify online-access-token by default for offline.

TIP

For more about online and offline tokens, read Online access tokens vs. Offline access tokens.

Example

Token exchange request:

curl -X POST \
  https://{shop}.genmystore.com/oauth2/token \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
      "clientId": "{client_id}",
      "clientSecret": "{client_secret}",
      "grantType": "token-exchange",
      "subjectToken": "{session_token}",
      "requestedTokenType": "online-access-token"
  }'

Token exchange response:

• Online token

{
  "accessToken": "3f56c8bf63277ef253027f17",
  "scope": "write_orders,read_products",
  "expiresIn": 86399,
  "associatedUser": {
	"id": 1818181818,
	"email": "junwei@example.com"
  }
}

• Offline token

{
  "accessToken": "3f56c8bf63277ef253027f17",
  "scope": "write_orders,read_products"
}

Authorization code grant

Non-embedded apps need to use the OAuth 2.0 Authorization Code Grant method to obtain access tokens, adhering to OAuth 2.0 industry standards.

Authorization code grant process

1. When users access an application on the Genstore platform, the platform directs them to the application configuration URL.
2. If installation and authorization have not been completed, the application needs to directs the user to the authorization page.
3. After the user grants authorization, the authorization center returns an authorization code.
4. The application uses the authorization code to request an access token.
5. Genstore returns the access token, and the application uses it to access the required resources.

Redirect to application configuration URL

When a user opens your app from the Genstore platform, Genstore redirects them to your app’s configuration URL with the parameters shopId, shop, timestamp, and hmac. You must validate the hmac to ensure the request is authentic.

Request format:

https://{APP URL}?shop={shop}&shopId={shopId}&timestamp={timestamp}&hmac={hmac}

Parameters:

• APP URL：Application configuration URL.
• shop：Merchant's store domain.。
• shopId：Shop ID.
• timestamp ：Timestamp。
• hmac ：Request signature。

Request authorization code

Request format:

https://{shop}.genmystore.com/admin/oauth2/authorize?clientId={client_id}&scope={scopes}&redirectUrl={redirectUrl}&state={nonce}&grantType={code}

Parameters:

• shop: Merchant's store domain.
• clientId: App's client ID.
• scope: Authorization scope
• redirectUrl: Callback URL, It must match the callback URL configured in the application.
• state: Used for app security checks, will be returned with the authorization code.
• grantType: Authorization method, value "code".

TIP

For more about online and offline tokens, read Online Access Tokens vs. Offline Access Tokens.

Redirect back with authorization code

The application obtains the authorization code through the redirection of the code parameter，Redirect URL format：

https://{redirectUrl}?shop={shop}&shopId={shopId}&state={state}&timestamp={timestamp}&code={code}&hmac={hmac}

参数说明：

• redirectUrl: App Callback URL
• shop：Merchant's store domain。
• shopId ：Shop ID。
• state：Used for app security checks, will be returned with the authorization code.
• timestamp ：Timestamp.
• code ：Authorization code。
• hmac ：Request signature。

Obtain access token via authorization code

Request format:

POST https://{shop}.genmystore.com/oauth2/token

Parameters:

• clientId: App's client ID.
• clientSecret: App's client secret.
• grantType: Authorization method, value "code".
• code: Authorization code.

Example

Request:

curl -X POST \
  https://{shop}.genmystore.com/oauth2/token \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
      "clientId": "{client_id}",
      "clientSecret": "{client_secret}",
      "grantType": "code",
      "code": "{code}",
  }'

Response:

• Offline token

{
  "accessToken": "3f56c8bf63277ef253027f17",
  "scope": "write_orders,read_products",
  "shopId": 988716383,
  "shopDomain":"xxx.genmystore.com"
}

Online access tokens vs. Offline access tokens

When creating an API access token, you can choose between two access modes: offline and online, with offline being the default setting.

Online access tokens

• Online access tokens are linked to a specific user within the store. The lifespan of these tokens corresponds directly to the user's active web session.
• This mode is particularly suitable for apps that interact with users over the internet and need to adhere to individual user permission levels.
• Online access tokens are intended for apps that require short-term access to the store and will be invalidated once the user logs out.

Offline access tokens

• Offline access tokens provide long-term access to the store without requiring user interaction, making them ideal for tasks like responding to webhooks or performing backend maintenance.
• Reauthorization of the app is not necessary unless the app is uninstalled or additional access scopes are required. The same token is issued every time the app is authorized for offline access.
• Tokens created with offline access are permanent. They remain active unless the app is uninstalled from the store.