1. Introduction to OAuth 2.0

Before your application can access HubRise data, the user needs to give your application permission. The HubRise API uses the OAuth 2.0 protocol for this purpose. This is the same method that services like Twitter and Facebook use to let applications post on your behalf.

The OAuth 2.0 flow is a series of interactions between:

  • A resource owner: the HubRise user
  • A client: your application, ie a program or a website making protected requests on behalf of the user
  • An authorization server: HubRise OAuth API, which issues an access token to the client. It is hosted at:
  • A resource server: HubRise API, which provides access your user data. It is hosted at:

Although it seems complicated at first, OAuth actually makes things simpler for both you and your users, and it dramatically reduces security risks for everyone:

  • Your application doesn't need to store your users' passwords
  • You can pick which permissions to request from a user. For example, users can grant your application access to their order list, without also needing to grant access to their customer list.
  • Users can easily revoke the access they grant a potentially insecure application, without needing to reset their password.

2. OAuth scopes

A scope controls the set of resources an access token can read and write. Users can see the scope before granting access to an application. It's recommended for application developers to limit the scope to what is strictly necessary to avoid being denied access.

A scope is a comma-separated list of:

  • 0 or 1 access-level set of permissions
  • And general permissions (eg. profile, or profile_with_email)

An access-level set of permissions is made of:

  • An access-level keyword: location or account
  • Followed by a comma separated list of permissions between square brackets. Each permission consists of:
    • A resource: orders, customer_list, all_customer_lists, catalog, or all_catalogs
    • A . character
    • Access rights: read or write

Examples of valid scopes:

  • profile_with_email: access to the user profile including email
  • location[orders.write,customer_list.write]: allows creating orders and customers for a chosen location
  • account[],profile: access to the user profile and to the customers from a chosen customer list

3. Web application workflow

3.1. Request authorization

When your application needs to access a user's data, it should redirect him to HubRise's OAuth server:

GET<<YOUR DOMAIN HERE>>/oauth_callback&[orders.write,customer_list.write,] HTTP/1.1

HubRise authenticates the user, prompts him to choose the location, account, catalog and customer list he's willing to connect, and obtain consent to access the requested scope. If the user is not logged in, he will be able to sign in or create an account.

HubRise server sends the result of the authorization to the provided URL. If the user approves the request, then the response contains an authorization code that looks like:

https://<<YOUR DOMAIN HERE>>/oauth_callback?code=ffae0047c4d6b9e02f95e76a3f6a32...

Once issued, the authorization code is valid for 10 minutes.

If the authorization fails, HubRise calls the URL with an error message passed as a parameter:

https://<<YOUR DOMAIN HERE>>/oauth_callback?error=access_denied


https://<<YOUR DOMAIN HERE>>/oauth_callback?error=expired

3.2. Get an access token

After receiving an authorization code, your application can retrieve an access token:

POST HTTP/1.1Content-Type: application/x-www-form-urlencoded---code=ffae0047c4d6b9e02f95e76a3f&*********

To which HubRise responds:

{ "access_token": "b9922a78d3ffab6b95e9d72e88", "location_id": "3r4s3-1", "catalog_id": "psmlf", "customer_list_id": "xab66"}

3.3. Connect to the API

Now that your application has an access token, it can call the API on behalf of the user. Calls to the API need to include a X-Access-Token HTTP header.

Here is a call to get location details:

GET HTTP/1.1X-Access-Token: b9922a78d3ffab6b95e9d72e88

4. Installed app workflow

This workflow is for native apps, as opposed to web apps. Non-SaaS EPOS systems should use this workflow.

The main difference with the Web app workflow is that the authorization code is displayed in the browser, and the user needs to copy/paste the code into the application.

You will need to embed the client secret into your application, which obviously means that it is not treated as a secret in this context.

The authorization request is made by opening a browser with this URL: redirect_uri=urn:ietf:wg:oauth:2.0:oob& scope=location[orders.write,customer_list.write,]

The special value of redirect_uri tells HubRise's OAuth server that the code should be displayed in the browser, rather than being sent to a callback URL.

If the user grants access to your application, the result will be a dialog where the user will be instructed to copy/paste the indicated authorization code into your application. Your application needs to provide a field for the user to paste the code. From there, your application can request an access token in the same way as a web application.

5. Connection reuse

The access_token returned by GET /oauth2/v1/token is specific to a client and a location. Reauthorizing the same location several times always returns the same initial token.

Important: if a different catalog (or customer list) is selected when reauthorizing the location, the token will no longer allow access to the former catalog (or customer list) when the new authorization completes.

You can bypass this behaviour and force a new token to be issued by passing a device_id parameter when redirecting the user to the authorization page, eg:

GET[orders.write,customer_list.write,] HTTP/1.1

If the provided device_id has never been authorized for the location, a new access token is returned. Otherwise, the access token previously associated with this device_id is returned.