Reporting Engine Onboarding

This is still a work in progress and for the short term will be a manual process

  1. Contact us directly at [api-support (at) powerepos.cloud] to setup your client credentials

    • We will need your company name, website and primary contact details
    • We will send you the following details:
      • ClientID - string - OAuth2 Client ID (public information)
      • ClientSecret - string - OAuth2 Client Secret (sensitive information)
    • This OAuth2 Client will be limited to handling service accounts attached to an organisation.
      • You will not be able to perform pasword grant requests using an end user's email/password

  2. Establish a connection with a PowerEPOS Organisation by having them create a Service Account with the following minimum permissions:

    • Reporting Data (View) - For access to aggregate queries
    • Raw Data (View) - For access to sales transaction queries
    • This service account may/may not be scoped to one or more outlets. This will happen transparently.

  3. Have the organisation hand over the service account username/password. They will also need to provide their unique organisation code.

  4. Using the PowerEPOS AuthServer and the OAuth2 Token endpoint at /authorisation/token, make a password grant request with the org_id parameter set to the Organisation Code that the organisation has provided you.

    The token will be valid for a duration defined here

    Specifying the offline_access scope will also return a refresh token that can be used to request more tokens without having to provide the service account creddentials. Using this will free you from having to store the service account username/password.

    For more information about making OAuth2 queries see oauth.com:

    • Password Grants
    • Refresh Token Grants
      • Please note that PowerEPOS Auth Server will return a new refresh token with these requests so that a connection can be maintained long term.

  5. All HTTP REST requests to the POSCore API will require the following header: Authorization: Bearer <YourAccessToken> otherwise you will be served a HTTP 401 / 403

Example Token Request

HTTP POST https://auth.powerepos.cloud/authorisation/token
Content-Type: application/x-www-form-urlencoded

grant_type=password&
client_id=<Your ClientID>&
client_secret=<Your ClientSecret>&
org_id=<Organisation Code that you want a ROS token for>&
username=<service account username>&
password=<service account password>&
scope=offline_access

JSON Encoded Response:

{
    "token_type": "Bearer",
    "access_token": "ey...3Y",
    "expires_in": 28800,
    "refresh_token": "abc"
    "svc": "https://example.service.uri/",
    "org_id": "<Organisation Code that you requested the token for>"
}

Discovering POSCore URI

The JSON Encoded Reponse to the token request will have a property called "svc" which will contain the service URI that you must use for any requests.

Alternatively, the access_token will be a JSON Web Token with custom claims (in the payload) that are defined at AuthServerClaims. AuthServerClaims.Service will hold the POSCore URI that THIS particular token is to be used with. This can be subject to change so ensure it's always decoded.