Authorization

OAuth 2.0

The Hike API uses OAuth 2.0 for API access and authorization.

Step 1: Request your App secret & Id

Login to your Partner Dashboard and add your application there by providing your application name and Return URI and click 'Add'. This will save your app in your 'My apps' list along with its newly generated 'App Secret' and 'App Id'. This is a primary requirement for making authenticated calls to Hike APIs.

📘

Developer credentials

Your developer key is separate to retail store account for which you are developing this integration/app. Developer is the gateway for your application/integration into Hike's eco-system.

Step 2: Send authorization request to connect your app with a store on Hike

You'll send authorization request to connect your application with a retail store on Hike. Send your request to the following URL along with parameters mentioned below: https://api.hikeup.com/oauth/authorize

Pareameters to include in your reuqest

  • response_type- permissions to request 'code' (required)
  • client_id - issued when you created your app (required) [App Id]
  • scope - permissions to request (see below) (required)
  • redirect_uri - URL to redirect back to (required)
  • state - unique string to be passed back upon completion (optional)

👍

Authorization request example

https://api.hikeup.com/oauth/authorize?response_type=code&client_id={client_id}&redirect_uri={redirect_uri}&state={state}&scope=all

📘

Scope

The 'scope' parameter is a space-separated list of oAuth scopes, indicating what data your app will access from the retail store on Hike.Currently Hike only provides 'all' as a value for this parameter. We will be introducing more options later on.

Possible responses

If the user authorizes your app, Hikeup will redirect back to your specified redirect_uri with a temporary code in a code GET parameter, as well as a state parameter if you requested one in the previous step. If the states don't match, the request may have been created by a third party and you should abort the process.

👍

Successful authorization response:

{redirect_uri}?code={code}&state={state}

❗️

Access denied

{redirect_uri}?error=access_denied

📘

Authorization code valid for 10 minutes

Authorization codes may only be exchanged once and expire 10 minutes after issuance. Once it has expired, please send a new authorization request.

Step 3 - Exchange authorization code for an access token

Now that you have an authorization code, exchange it for an access token using the oauth/token API method: https://api.hikeup.com/oauth/token

  • client_id - issued when you created your app (required)
  • client_secret - issued when you created your app (required) [App secret]
  • code - Temporary authorization code received in step 2 (required)
  • redirect_uri - must match the originally submitted URI (if one was sent)
  • grant_type - this is always 'authorization_code'

📘

Access token request

Data should be sent as “application/x-www-form-urlencoded” encoded body of a POST request.

Response

Receive a JSON response containing your access_token among other things.

{
    "access_token": "fdgdfg54df6g8df6g46d5fg46d5fg46d5fg4",
    "token_type": "Bearer",
    "expires": 498465465,
    "expires_in": 64646,
    "refresh_token": "Ksdfsd54fs65d4fs6d5f4s6d5f4s6d5f4s6d5f4"
}

📘

These access tokens are also known as bearer tokens.

You can then use this token to call API on behalf of the user (Store). The token will continue functioning until the installing user either revokes the token and/or uninstalls your application.

🚧

User tokens issued on behalf of stores.

Step 4. Refresh the access token

Access tokens are valid for set amount of time. When an access token expires, get your application to request a new access token using the refresh token received in Step 3. Use the below-mentioned URL and parameters to request a new access token: https://api.hikeup.com/oauth/token

  • client_id - issued when you created your app (required)
  • client_secret - issued when you created your app (required)
  • refresh_token – from step 3
  • grant_type – this is always refresh_token

Response

Receive a JSON response containing refreshed new access_token along-with other details including its 'exires in' value.

{
    "access_token": "Artygbmwpekofkmlknufsdjnflopkdfgdfhgj",
    "token_type": "Bearer",
    "expires": 1387145621,
    "expires_in": 604800,
    "refresh_token": "J3F62YPIQdfJjJia1xJuaHp7NoQYtm9y0WadNBTh"
}

Why use OAuth?

At a first glance it might seem a bit too much, however, in reality OAuth makes things simpler for both you and the retailers using your application, Most importantly, it reduces security risks for everyone. Here are some of the most important benefits of using OAuth:

  • Your application doesn't need to store retail store admin’s passwords and it definitely shouldn’t!
  • Merchants don't need to sign in to Hike to every time your application send/receive data to/from Hike.
  • You can set which permissions to obtain from a retail store. In other words you can define the scope. For example, retail stores can grant your application access to their products list, without also needing to grant access to their sales history.
  • If needed, retail stores can revoke a possibly insecure application's access without affecting other applications or needing to change their own password.