ShopBase Developers
  • Getting started
  • Build An App
    • Making your first request
      • Authentication
        • Public apps
        • Private apps
        • OAuth
        • API access scopes
      • Rest API References
        • Rate limits
      • Using webhooks
        • Webhook events and topics
      • Response status codes
    • How to submit an app to ShopBase App Store
    • Getting your app approved
      • App requirements
      • Testing your app
      • Submitting your app
      • The review process
  • BUILD A THEME
    • Getting started building themes
    • Theme development resources
      • Connect to your store & start developing
      • Theme structure
      • Theme object, methods, and props
      • Theme editor
        • How to update configure for theme editor
    • How to submit a theme to ShopBase Theme Store
    • Storefront SDK
  • Test and Debug app
    • Debug apps with Postman
  • Tutorial
    • Manage orders and shipping
      • Manage orders with the REST Admin API
        • Transaction
        • Order
      • Edit an existing order with the Admin API
      • Manage fulfillments with Fulfillment and FulfillmentService resources
      • Get a country field using Admin API
  • Integrate a payment gateway
    • How to create your payment gateway on ShopBase
    • Technical Specifications
Powered by GitBook
On this page
  • Terminology
  • The OAuth flow
  • Step 1: Get client credentials
  • Step 2: Ask for permission
  • Step 3: Confirm installation
  • Step 4: Making authenticated requests
  • Update OAuth scopes
  • Verification

Was this helpful?

  1. Build An App
  2. Making your first request
  3. Authentication

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.

PreviousPrivate appsNextAPI access scopes

Last updated 3 days ago

Was this helpful?

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

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 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

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.

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.

{
  "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": "john@example.com",
    "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 must include the following headers:

  • X-ShopBase-Access-Token: {access_token}

  • X-ShopBase-Token-Secret: {token_secret}

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.

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.

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")

You need to to identify the client during the authorization process.

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

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

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

Starting from May 21, 2025, the X-ShopBase-Token-Secret header is required for all API requests. For details on how to generate and manage your Token Secret, please refer to the .

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

You can view or below example in Ruby code.

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

OAuth 2.0 specification
authorization code grant flow
retrieve an API key and secret key
Verification
is a valid hostname
online access mode
Manage Access from App to ShopBase section
app authorization link
SampleApp example
Using webhooks