OAuth - Authentication

Your app cannot read StoreHippo 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 will walk you through the authorization process (described in greater detail by the OAuth 2.0 specification).

Step 1: Get the credentials

When you signup your app with StoreHippo, you would be provided with the ClientID and Client Secret Key.
You will need to retrieve a ClientID and Client Secret Key as the client uses them to identify itself during the authorization process.

Step 2: Ask for permission

The first step of the process is to get authorization from the user. This is done by displaying a prompt provided by StoreHippo

To show the prompt, redirect the user to this URL:

https://{store}.storehippo.com/admin/oauth/authorization?client_id={client_id}&scope={scopes}&redirect_uri={redirect_uri}&state={nonce}

With these substitutions made:

• {store} - substitute this with the name of the user’s shop.
• {client_id} - substitute this with the app’s client_id.
• {scopes} - substitute this with a comma-separated list of scopes described below. For example, to write orders and read customers use scope=write_orders,read_customers.
• {redirect_uri} - (Required) substitute this with the URL where you want to redirect the users after they authorize the client. The complete URL specified here must be identical to one of the Application Redirect URLs.
• {nonce} - a randomly selected value provided by your application, which is unique for each authorization request.

Step 3: Confirm installation

When the user clicks the Install button in the prompt, they will be redirected to the client server as specified above. One of the parameters passed in the confirmation redirect is the Authorization Code.
The authorization code can be exchanged once for a permanent access token. The exchange is made with a request to the store.

To get the access_token, you’ll need to make a POST request to:

POST https://{store}.storehippo.com/admin/oauth/token

With {store} substituted for the name of the user’s store and with the following parameters provided in the body of the request:

• client_id
  The client_id for the app.
• client_secret
  The client_secret for the app.
• code
  The authorization code provided in the redirect described above.
• redirect_uri
  Substitute this with the URL where you want to the access token to be provided.
• grant_type - Must be authorization_code

If everything goes right and the request is successful, you’ll receive a 200 response containing a JSON body like this:

Using cURL

curl https://{store}.storehippo.com/admin/oauth/token -d 'grant_type=authorization_code&code={your_code}&client_id={your_client_id}&client_secret={your_client_secret}' -X POST

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

Step 4: Making authenticated requests

Now that the client has obtained an API access token, it can make authenticated requests to the REST API. The access token is a bearer token so these requests are accompanied with a header Authorization: Bearer {access_token} where {access_token} is replaced with the permanent token.

Scopes

Part of the authorization process requires specifying which parts of a store’s data the client would like access to. A client can ask for any of the following scopes:

• read_orders, write_orders
  Access to Orders, Transactions.
• read_customers, write_customers
  Access to Customers.
• read_products, write_products
  Access to Products, Categories, Collections and Brands .
• read_content, write_content
  Access to Blogs, Pages and Redirects.
• read_script_tags, write_script_tags
  Access to Script Tags.
• read_controllers, write_controllers
  Access to Startup Controllers.
• read_checkouts, write_checkouts
  Access to Checkouts.