Skip to main content

Readme

Hii Retail Oauth2 Client Management Service

What is OCMS​

OCMS lets external services (that are not a part of Hiiretail cloud environment) make secure interactions with Hiiretail APIs. The service lets applications register themselves in OCMS as an OAuth2 client, retrieve JWT tokens, and securely talk to Hiiretail APIs. Usually this service is used by tenant's developer(s).

When to use?​

If you have an app, that does not have human user that is logging in to app with federated login, you should use OCMS. Examples - POS software, CI/CD Pipelines etc.

Concepts​

There are some important things, that you MUST know & understand, before diving into service.

General flow, when working with OCMS​

  1. Find Registration Template in OCMS UI here - https://[your-tenant].hiiretail.com/ocms/templates that was provided by Extenda employees. It is usually created by Extenda employee upfront. Must be done once for every application.

  2. (Optional) Create Software Statement SS is created using Registration Template here - https://[your-tenant].hiiretail.com/ocms/statements. It is providing additional layer of security. Can be done multiple times for same Registration template

  3. Register an OAuth client in OCMS from application, and get client_id & client_secret. This part is done without UI, apps should implement this logic. Additional info about Dynamic client registration Must be done on each app instance startup.

  4. Use client_id & client_secret to get short-lived JWT tokens, to access Hiiretail APIs. Additional info about OAuth authentication Must be done each hour, after JWT token expired.

  5. (Optionally) Clean up, if app no longer needs client_id & client_secret. Additional info about OAuth client cleanup Should be done on each app instance stop.

OpenAPI Spec​

All http calls, that will be referenced here will be in OpenAPI spec, that can be found here