# SSM Input Api

SSM apps must authenticate using the OAuth 2.0 specification (opens new window)to use SSM’s API resources. This guide shows you how to authenticate an app using OAuth.

# The OAuth flow

SSM uses OAuth 2.0’s authorization code grant flow (opens new window) to issue access tokens on behalf of users. The following diagram illustrates the OAuth flow based on the actions of the merchant, your app, and SSM.

1. The merchant makes a request to install the app.
2. The app redirects to SSM to load the OAuth grant screen.
3. SSM displays a prompt to the merchant to give authorization to the app, and prompts the merchant to log in if required.
4. The merchant consents to the scopes and is redirected to the redirect_uri.
5. The app makes an access token request to SSM including the client_id, client_secret, and code.
6. SSM returns the access token.
7. The app uses the access token to make requests to the SSM API.
8. SSM returns the requested data

# 1. Get API credentials

The first step is to retrieve an API key and API secret key. These API credentials identify your app during the authorization process. In order to get these please contact the support team.

# 2. Ask for permission

Before an app can access any store data, a merchant must grant permission to the app. Granting permission happens when a merchant clicks the link to install your app.

# How the installation flow works

After a merchant clicks the link to install your app, your app receives a GET request on the app URL path that you specified for the support team. Requests to this URL path from a merchant who is logged into the SSM App Store include the hmac query parameters.

You need to verify the authenticity of these requests using the provided HMAC. For more information, refer to Verification.

# Installation permissions prompt

SSM shows the following prompt to receive authorization from the merchant.

Show the installation permissions prompt To show the prompt, redirect the merchant to the following URL with the query parameters defined below:

https://platform.supersalesmanagerapp.com/#/portail/oauth/partners?client_id={api_key}&redirect_uri={redirect_uri}

# 3. Confirm installation

When the merchant clicks the install button in the prompt, they’re redirected to your app's server. The authorization_code is passed in the confirmation redirect:

https://example.org/some/redirect/uri?code={authorization_code}&hmac=da9d83c171400a41f8db91a950508985}

# Security checks

Before you continue, make sure that your app performs the following security checks. If any of the checks fail, then your app must reject the request with an error, and must not continue.

• The hmac is valid and signed by SSM.

# 4. Get a permanent access token

If all security checks pass, then you can exchange the access code for a permanent access token by sending a request to the shop’s access_token endpoint:

POST https://api.supersalesmanagerapp.com/api/oauth/partners/token

In your request, you must provide in the request body:

The server responds with an access token:

{
  "access_token": "f85632530bf277ec9ac6f649fc327f17"
}

The following values are returned:

# 5. Make authenticated requests

After your app has obtained an API access token, it can make authenticated requests to the SSM API. These requests a Bearer token like this: Bearer {access_token} where {access_token}is replaced with the permanent token.

# Verification

Every request or redirect from SSM to your app's server includes an hmac parameter that can be used to verify the authenticity of the request from SSM. For each request, you must remove the hmac entry from the query string and process it through an HMAC-SHA256 hash function.

The following is an example of a query string. However, request parameters provided by Shopify are subject to change. Your verification strategy shouldn't depend on the parameters in the following example:

"code=0907a61c0c8d55e99db179b68161bc00&hmac=700e2dadb827fcc8609e9d5ce208b2e9cdaab9df07390d2cbca10d7c328fc4bf"

# IDs array parameter

If your query string includes an ids array parameter, then the query string is parsed so that ids[]=1&ids[]=2 gets converted to ids=["1", "2"] before the signature is generated.

# Remove the HMAC

To remove the hmac, you can transform the query string to a map, remove the hmac key-value pair, and then lexicographically concatenate your map back to a query string. This leaves the remaining parameters from the example query string:

"code=0907a61c0c8d55e99db179b68161bc00"

# Process through the hash function

You can process the string through an HMAC-SHA256 hash function using the secret key. The message is authentic if the generated hexdigest is equal to the value of the hmac parameter.

The following Ruby example shows how to process the string through a hash function:

digest = OpenSSL::Digest.new(’sha256’)
secret = "hush"
message = "code=0907a61c0c8d55e99db179b68161bc00&shop=some-shop.myshopify.com&state=0.6784241404160823&timestamp=1337178173"

digest = OpenSSL::HMAC.hexdigest(digest, secret, message)
ActiveSupport::SecurityUtils.secure_compare(digest, "700e2dadb827fcc8609e9d5ce208b2e9cdaab9df07390d2cbca10d7c328fc4bf")