Link Search Menu Expand Document
Gorilla Engine
Table of contents

Product Hub - Introduction for Manufacturers

Welcome to the Gorilla Engine Product Hub API, a comprehensive licensing and delivery platform designed specifically for virtual instrument and effect plugin manufacturers using Gorilla Engine by UJAM Inc.

Overview

The Product Hub API and its management web frontend enables manufacturers to integrate licensing and distribution capabilities directly into their existing systems, providing a seamless experience for both you and your end users. Whether you’re looking to manage licenses, deliver digital products, or both, our API provides the tools you need to scale your business efficiently.

What You Can Do

Licensing Management

  • Create and assign licenses to your customers
  • Track license usage and activations
  • Transfer licenses between users when needed
  • Support multiple license types (Standard, NFR, Free, etc.)

Product Delivery

  • Upload installers for your plugins and products
  • Distribute updates seamlessly to your user base
  • Manage product releases and builds
  • Deliver beta and alpha builds through distribution channels to selected audiences

User Management & End User Authentication

While Product Hub maintains user records to assign licenses to, those users do not “live” inside Product Hub. It is not an identity management system. Instead we connect to either your existing Auth0 account or to any custom user management system able to provide a login route. Login requests from your end users to Product Hub - e.g. for plugin activations with username & password - will be forwarded to your system in order to validate the user credentials. We do not store any credentials or sensitive information of your customers other than their email address and potentially an external id which can be used to identify the user in your identity management system.

Integration Scenarios

Product Hub can be utilized “as is” meaning you manage your products and licenses using its web frontend and integrate a ready-made licensing client library in your products to handle activation, trial activations as well as update checking and downloading.

If you like you can integrate deeper and interact with the API to push users and licenses into the system when purchases are made in your webshop. Going a step further is also possible to e.g. build your own dashboards showing the data you are interested in.

Integration of the JavaScript client library in your products

The @gorilla-engine-sdk/ge-product-hub client library provides:

  • Product activation with license (email & password)
  • Trial activation and time tracking
  • Local persistence for offline validation
  • Built-in signature verification
  • Hardware fingerprint detection

To get started

  1. Contact UJAM to sign the Product Hub Add-On agreement and set up your manufacturer account
  2. Log in to Product Hub’s management web frontend and create a first product
  3. Integrate the ge-product-hub client library in your product to build your activation UX with the user’s email & password

Deep API integration

API Overview

This is just an introductory overview to illustrate the capabilities of the API. There are many more routes available but these are usually the most useful ones for integration. For actual integration work we will provide you with access to our full Swagger documentation of the API containing all the details like routes, their parameters, authorization header requirements, expected responses, status codes and everything needed to properly interact with the API.

Once you obtained the password from your designated UJAM contact, you can access the full API documentation here: https://producthub.ujam.com/api-docs

User Management
  • GET /api/v1/users - Search for users or find user by email
  • POST /api/v1/users - Create a new user
  • GET /api/v1/users/{id} - Get user details
  • GET /api/v1/users/{id}/licenses - Get user licenses
  • POST /api/v1/users/{id}/licenses - Create license for user
  • POST /api/v1/users/tokens - Log in user / create user token
  • POST /api/v1/users/tokens/verify - Verify user token
Product Management
  • GET /api/v1/products - List products
  • GET /api/v1/products/{id} - Get product details
  • POST /api/v1/products/{id}/licenses - Create license for product (with user creation)
  • GET /api/v1/products/{id}/licenses - Get product licenses
  • GET /api/v1/products/{id}/builds - Get product builds
  • GET /api/v1/products/{id}/builds/{build_id} - Get specific build
  • GET /api/v1/products/{id}/trials - Get product trial activations
  • GET /api/v1/products/{id}/releases - List product releases
  • GET /api/v1/products/{id}/releases/{release_id} - Get specific release
  • GET /api/v1/products/{id}/distribution - Get product distribution map
License Management
  • GET /api/v1/licenses/{id} - Get license details
  • PATCH /api/v1/licenses/{id} - Update license
  • PATCH /api/v1/licenses/bulk-update - Bulk update licenses
  • POST /api/v1/licenses/{id}/activations - Activate license (offline activation)
Product Activation (End User / Plugin)

These endpoints are called by your end users’ DAW plugins to activate products and trials.

  • POST /api/v1/clients/any/products/{product_id}/activations - Activate product
  • POST /api/v1/clients/any/products/{product_id}/trials - Activate product trial

Authentication & Authorization

Machine-to-Machine (M2M) Authentication

For server-to-server integrations, the Product Hub API uses API key-based authentication.

Signing of M2M requests

Machine to machine (M2M) requests need to be signed. The signature, key id and current timestamp are then sent along in the Authorization header.

Prerequisites

Create an API key using the management webfrontend. On creation the public & private key and the key id will be shown. Make sure to keep the private key somewhere safe as it will only be shown once. UJAM does not store the private key and can not restore it if it gets lost.

To create the signature, the HTTP method, the URL path and query, the body of the request and the current timestamp are joined by a : between them. The resulting message is then signed with the ed25519 private key shown during API key creation. The timestamp must be in milliseconds UTC.

The key identifier, the timestamp and generated signature are then joined by a : between each field. The resulting string is then sent along in the Authorization header of the request.

How to generate the signature in Javascript:

import { sign } from "node:crypto";
// Key ID and private key from the API. Same for each request
const KEY_ID = "f6c697ab-0a38-4026-a364-33edbfe9b6d2";
// watch out for indentation! There must not be any tabs or whitespace other than newlines
const PRIVATE_KEY = `-----BEGIN PRIVATE KEY-----
...
-----END PRIVATE KEY-----`;

// Different for each request
const HTTP_METHOD = "GET";
const URL_PATH_AND_QUERY = "/api/v1/products";
const BODY = {}; // No body
const TIMESTAMP = Date.now();

// prettier-ignore
const message = `${HTTP_METHOD}:${URL_PATH_AND_QUERY}:${JSON.stringify(BODY)}:${TIMESTAMP}`;

const signature = sign(null, message, privateKey).toString("base64");
const authorizationHeader = `M2M ${KEY_ID}:${TIMESTAMP}:${signature}`;

// Then set the `Authentication` header like so:
const response = await fetch(
  "https://producthub.gorilla-engine.com/api/v1/products",
  {
    headers: {
      Authorization: authorizationHeader,
    },
  }
);

To get started

  1. Contact UJAM to set up your manufacturer account
  2. Generate API keys through the Product Hub interface
  3. Use these keys in your API requests

Best Practices:

  • Store API keys securely (environment variables, key management systems)
  • Use different API keys for different environments (staging, production)
  • Include a descriptive comment when creating API keys for future reference

Next Steps

Ready to integrate? Contact UJAM to begin your Product Hub journey and transform how you deliver licenses and products to your customers.

For technical questions or support, reach out to the Product Hub team through your designated UJAM contact.