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:

• shop: Merchant's store name.
• 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": "[email protected]"
  }
}

• 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. User accesses the app, which directs them to the authorization page.
2. After user consent, the authorization center returns an authorization code.
3. The app uses the authorization code to request an access token.
4. Genstore returns the access token, which the app uses to access required resources.

Request authorization code

Request format:

POST https://{shop}.genmystore/oauth2/authorize?clientId={client_id}&scope={scopes}&redirectUri={redirect_uri}&state={nonce}&requestedTokenType={access_mode}

Parameters:

• shop: Merchant's store name.
• clientId: App's client ID.
• scope: Authorization scope
• redirectUri: Callback URL
• state: Used for app security checks, will be returned with the authorization code
• requestedTokenType: Sets the access mode. Specify online-access-token by default for offline.

TIP

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

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:

• Online token

{
  "accessToken": "3f56c8bf63277ef253027f17",
  "scope": "write_orders,read_products",
  "expiresIn": 86399,
  "associatedUser": {
	"id": 1818181818,
	"email": "[email protected]"
  }
}

• Offline token

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

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.