OAuth

Your app cannot read ShopBase data without authenticating first. It must get permission from a user before gaining access to any of the resources in the REST API.

This guide walks you through the authorization process, described in greater detail by the OAuth 2.0 specification.

Terminology

Before learning more about the details of the authorization process, make sure that you're familiar with some of the key terms used in this guide:

• Client: Any app that wants access to a shop's data. A user must grant permission before the client can access any data.

• API: ShopBase's REST API, which the client can use to read and modify shop data.

• User: A ShopBase account holder, usually a merchant. The user gives permission to a client to access shop data through the REST API.

The OAuth flow

ShopBase uses OAuth 2.0's authorization code grant flow to issue access tokens on behalf of users.

1. The merchant makes a request to install the app.

2. The app redirects to ShopBase to load the OAuth grant screen and requests the required scopes.

3. ShopBase displays a prompt to receive authorization and prompts the merchant to login 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 ShopBase including the client_id, client_secret, and code.

6. ShopBase returns the access token and requested scopes.

7. The app uses the token to make requests to the ShopBase API.

8. ShopBase returns the requested data.

Step 1: Get client credentials

You need to retrieve an API key and secret key to identify the client during the authorization process.

Step 2: Ask for permission

After the user clicks an install link, your app receives a GET request on the app URL path specified in the Partner Dashboard. Requests to this route from a user that is logged into the ShopBase App Store include the shop, timestamp, and hmac query parameters. If your install link doesn't originate from the ShopBase App Store, then you need to provide the shopparameter yourself or implement other handling to get the user's shop.

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

To show the prompt, redirect the user to the following URL with the query parameters defined below:

https://{shop}.onshopbase.com/admin/oauth/authorize?client_id={api_key}&scope={scopes}&redirect_uri={redirect_uri}

• {shop}: The name of the user's shop.

• {api_key}: The app's API Key.

• {scopes}: A comma-separated list of scopes. For example, to write orders and read customers, use scope=write_orders,read_customers. Any permission to write a resource includes the permission to read it.

• {redirect_uri}: The URL to which a user is redirected after authorizing the client. The complete URL specified here must be added to your app as a whitelisted redirection URL, as defined in the Partner Dashboard.

Step 3: Confirm installation

When the user clicks the Install button in the prompt, they're redirected to the client server as specified above. The authorization_code is passed in the confirmation redirect.

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

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

• The hmac is valid. The HMAC is signed by ShopBase as explained below, in Verification.

• The hostname parameter is a valid hostname, ends with onshopbase.com, and does not contain characters other than letters (a-z), numbers (0-9), dots, and hyphens.

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://{shop}.onshopbase.com/admin/oauth/access_token.json

In your request, {shop} is the name of the user's shop and the following parameters must be provided in the request body:

• client_id: The API key for the app, as defined in the Partner Dashboard.

• client_secret: The API secret key for the app, as defined in the Partner Dashboard.

• code: The authorization code provided in the redirect.

The server responds with an access token:

{
  "access_token": "f85632530bf277ec9ac6f649fc327f17",
  "scope": "write_orders,read_customers"
}

The following values are returned:

• access_token: An API access token that can be used to access the shop's data as long as the client is installed. Clients should store the token somewhere to make authenticated requests for a shop's data.

• scope: The list of access scopes that were granted to the application and are associated with the access token. Due to the nature of OAuth, it's always possible for a merchant to change the requested scope in the URL during the authorize phase, so the application should ensure that all required scopes are granted before using the access token. If you requested both the read and write access scopes for a resource, then check only for the write access scope. The read access scope is omitted because it's implied by the write access scope. For example, if your request included scope=read_orders,write_orders, then check only for the write_orders scope.

If online access mode is requested, then the server responds with an access token and additional data:

{
  "access_token": "f85632530bf277ec9ac6f649fc327f17",
  "scope": "write_orders,read_customers",
  "expires_in": 86399,
  "associated_user_scope": "write_orders",
  "associated_user": {
    "id": 902541635,
    "first_name": "John",
    "last_name": "Smith",
    "email": "[e-mail]",
    "email_verified": true,
    "account_owner": true,
    "locale": "en",
    "collaborator": false
  }
}

The following values are returned:

• expires_in: The number of seconds until the access token expires.

• associated_user_scope: The list of access scopes that were granted to the app and are available for this access token, given the user's permissions.

• associated_user: Information about the user who completed the OAuth authorization flow.

The email field in this response appears regardless of the email verification status. If you're using emails as an identification source, then make sure that the email_verifiedfield is also true. You can use the id field to uniquely identify a single user.

Step 4: Making authenticated requests

After the client has obtained an API access token, it can make authenticated requests to the REST API. These requests are accompanied with a header X-ShopBase-Access-Token: {access_token} where {access_token} is replaced with the permanent token.

Update OAuth scopes

After the user has agreed to install your app, you might want to change the granted scope. For example, you might want to request additional scopes if your integration requires access to other API endpoints.

To change scopes, redirect your users to the app authorization link and request authorization of new permissions:

https://{shop}.onshopbase.com/admin/oauth/authorize

In the URL, {shop} is the users myshopbase domain and the oauth/authorize link includes the required parameters.

Verification

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

By way of example, consider the following query string:

code=0907a61c0c8d55e99db179b68161bc00&hmac=700e2dadb827fcc8609e9d5ce208b2e9cdaab9df07390d2cbca10d7c328fc4bf&shop=some-shop.onshopbase.com&timestamp=1337178173

This query string is merely an example, and the request parameters provided by ShopBase could be subject to change. Your verification strategy should not depend on the parameters in the example above.

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&shop=some-shop.onshopbase.com&timestamp=1337178173

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 hex digest is equal to the value of the hmac parameter.

You can view SampleApp example or below example in Ruby code.

Ruby Example:

digest = OpenSSL::Digest.new('sha256') 
secret = "YOUR_APP_SECRET_KEY" 
message = "code=0907a61c0c8d55e99db179b68161bc00&shop=some-shop.onshopbase.com&timestamp=1337178173"

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

Note: The HMAC verification procedure for OAuth is different from the procedure for verifying webhooks. To learn more about HMAC verification for webhooks, see Using webhooks.