× Docs Platform Dashboard Extensions Wallets Merchants Sign in

Building

In addition to the officially supported Rehive extensions, it is possible to build custom extensions as a third party.

For a third party integration to count as a Rehive extension it needs to adhere to a list of requirements set out by the Rehive team. These are detailed in the Requirements section.

Extensions and the platform communicate to each other via two primary methods:

  • API calls from the extension to the platform.
  • Webhook events (selected from a list of presets) originating from the platform.

This allows for complex additional logic to be built on top of the existing platform. In its simplest form, building an extension on Rehive is a process of working out how you want to use the above two methods to add extra functionality to Rehive.

How extensions work

Extensions are web services that have been designed to operate using the Rehive platform as primary source of information (whether this be for authentication, validation, data or events).

We will use the Notification Extension (an officially supported extension in Rehive) as an example as it contains all the main elements of an extension that interacts with the Rehive ecosystem. The Notification extension has 3 elements:

  1. Admin API endpoints, which admins (authenticated against the platform) can use to add and manage notifications that should be triggered by certain events in the platform.
  2. An endpoint for receiving webhook events from the platform and processing them in accordance with the settings configured in the previous point.
  3. End user API endpoints, which users can use to manage what notifications they want to receive.

The Notification Extension combines the two elements of platform communication: webhooks and API calls. This can be seen in the following summaries:

Firstly, when an admin user accesses the API endpoints on the notification extension, the extensions sends the users token to the platform in an API call to authorize that the user exists on the platform (and is an admin or service user). Once this is done (and the user is authorized) the extension can find the information it needs for the admin (and its company) and return a list of relevant notifications.

Secondly, when a webhook is received by the extension on its webhook endpoint, it validates the secret sent with the webhook and matches it to a company. Once this is done the extension can find relevant notifications within the extension’s database and send out email, SMS and push notifications accordingly.

Thirdly, when an end user accesses the API endpoints on the notification extension it does the same authorization check as the admin user one except now it does not ensure the user is in the admin or service group. Once authorized the extension can return a list of notification settings it has stored for that user.

Extension integration

There are many ways to integrate extensions into the Rehive ecosystem. The following diagram shows how to do so using Rehive for authentication in addition to supporting a custom endpoint that provides access to resources normally only accesible to admin users:

Dashboard image

The flow above is stateless (REST), which is recomended when building web APIs. A detailed breakdown can be found below:

A. Call the login endpoint

eg. https://api.rehive.com/3/auth/login/

Call the rehive login endpoint from within the client-side web or mobile app..

If the login attempt is successful it will return a token that can be used for subsequent requests to Rehive.

The client should save the token to session or local storage so that all future requests can use it for authorization.

B. Call an endpoint on the custom extension

eg. https://custom.extension.domain/custom/transactions/

From the client-side call a custom endpoint on the custom extension or integration.

Include an Authorization token in the headers so that the extension can use it to authorize the user.

C. Call the authorization endpoint

eg. https://api.rehive.com/3/auth/

When the extension receives requests it can grab the Authorization header value and forward it to the authorization endpoint on Rehive.

If Rehive matches the Authorization token to a real user it will return successfully and the custom extension can continue processing the request as the user is now authorized to continue.

If Rehive cannot find a user for that token it will instead return an error and the custom extension should also stop processing immediately as the user is not authorized to continue.

The custom extension may also want to perform additional authorization (like ensuring the user is in a certain group or matching it against some other custom rules).

D. Call an admin endpoint

eg. https://api.rehive.com/3/admin/transactions/

Once the user is authorized, the custom extension can make admin API calls to the platform to get permission-restricted data that is normally only available to users with admin permissions.

For example, if the custom extension needs to get a list of all transactions from all users it can call the Rehive admin transactions endpoint.

A separate Authorization token (that is associated to a user who has the required permissions) should be attached to these admin API requests. For instance a user in the service group that is configured to view transactions.

The admin token can be stored on the custom extension server (as an env variable is probably best). It should never be returned to the client in any way or exposed through any interface to end-users.

Extension users

If an extension requires access to the platform API, then the extension will need to store an authentication token for a “machine user” that will make request to the platform.

Machine users should be created as part of the service group in the platform (called the extension group in the dashboard). The user can then be used internally with only the minimum permissions required to operate the extension. There should be one user per extension (per company), and they should never be shared across multiple extensions.

Rehive provides a built in mechanism for machine users once an extension has been listed within the platform’s services list (privately or publicly). For custom extensions, that a developer does not intend to incorporate into the Rehive extensions ecosystem, permissions will have to be manually added to the extension user through the API or the dashboard. These users and integrations are outside of the domain of Rehive and will be developers responsibility.

Within the Rehive extensions ecosystem, once an extension has been approved and included in the public extensions list then the population of permissions on an extension users is automated (based on the extension configuration).