​

Register and authenticate add-ons

💡 Before you start Add-ons (also called published add-ons) are third-party integrations that can be installed by Nexudus customers. If you’re building a custom integration for your own space only, you may not need this flow — consider using a standard API access token instead.

​

Overview

​

Step 1: Register your add-on

POST /api/apps/applications
Content-Type: application/json
Authorization: Basic <credentials>

{
  "Name": "My Add-on",
  "ShortDescription": "A brief description",
  "Description": "<p>Full HTML description</p>",
  "InstallUrl": "https://myapp.com/install",
  "Published": false,
  "RequiredRoles": [1, 2]
}

​

Step 2: Retrieve your application credentials

GET /api/apps/applications/my
Content-Type: application/json
Authorization: Basic <credentials>

[
  {
    "Name": "My Add-on",
    "ApplicationKey": "f36292c02d9c438d98d8c9eb34897c90",
    "SecretKey": "b5d83da7a...7febc62d8dc",
    "InstallUrl": "https://myapp.com/install",
    "Published": false,
    "RequiredRoles": [1, 2]
  }
]

​

Step 3: Handle the installation callback

https://myapp.com/install?
a=f36292c02d9c438d98d8c9eb34897c90&
t=c90e30fca71a4c37810a292b99d4d4f2&
d=634963729314011098&
h=785a10afef749b1c26cc3c5eb3989082&
b=subdomain&
e=user@example.com

​

Validating the request

1. Take the parameters token (t), applicationKey (a), and timespan (d).
2. Sort them alphabetically.
3. Join them with a pipe (|) separator.
4. Append your Secret Key to the end.
5. Calculate the MD5 hash of the resulting string.
6. Compare your calculated hash with the h parameter.

// Extract parameters from the request
var token   = Request.QueryString["t"];
var appKey  = Request.QueryString["a"];
var timespan = Request.QueryString["d"];
var hash    = Request.QueryString["h"];
var secret  = ConfigurationManager.AppSettings["SecretKey"];

// Calculate expected hash
var param = new[] { token, appKey, timespan };
Array.Sort(param);  // Sort alphabetically
var joined = string.Join("|", param);
var input  = joined + secret;
var expectedHash = MD5Hash(input);

// Validate
if (expectedHash != hash)
{
    // Request is not from Nexudus — reject it
    return HttpUnauthorized();
}

const crypto = require('crypto');

// Extract parameters from the request (Express.js example)
function installHandler(req, res) {
  const { t: token, a: appKey, d: timespan, h: hash } = req.query;
  const secret = process.env.NEXUDUS_SECRET_KEY;

  // Calculate expected hash
  const params = [token, appKey, timespan].sort();  // Sort alphabetically
  const joined = params.join('|');
  const input = joined + secret;
  const expectedHash = crypto.createHash('md5').update(input).digest('hex');

  // Validate
  if (expectedHash !== hash) {
    return res.status(403).send('Invalid request');
  }

  // Generate authentication token
  const authToken = crypto.createHash('md5')
    .update(token + secret)
    .digest('hex');

  // Store authToken securely for subsequent API calls
  // ...
}

​

Generating the authentication token

var authToken = MD5Hash(token + secret);

const authToken = crypto.createHash('md5')
  .update(token + secret)
  .digest('hex');

​

Step 4: Make authenticated API requests

GET /api/businesses
Authorization: Basic QWxhZGRp...lc2FtZQ==

💡 Note The authentication token is generated once during installation and is tied to the specific customer account that installed your add-on. You should store this token securely for subsequent API calls.

​

What happens during installation

1. Creates an API access user — A new system user is created with the email format {applicationKey}_{businessId}_api@nexudus.com and APIAccess = true. This user is linked to your add-on.
2. Records the installation — An InstalledApplication record is created, linking your application to the customer’s business.
3. Generates credentials — The authentication token is computed and passed to your installation URL.
4. Redirects to your app — The user is redirected to your Installation URL with the generated parameters.

​

Related entities

​

Submit your application for approval

1. Update your application details — Make sure the following fields are meaningful and accurate:

   Field	Guidance
   Logo	Upload a clear, professional logo that represents your brand.
   Name	Use a descriptive name that clearly communicates what your add-on does.
   Description	Provide a detailed and accurate description of your add-on’s features and benefits.

2. Send an approval request — Email support@nexudus.com with the following information:
   • Your add-on URL (the public URL where your add-on is hosted)
   • Your Privacy Policy URL
   • Your Terms of Service URL
   The Nexudus team will review your submission and get back to you once the approval process is complete.

​

Best practices

• Store your Secret Key securely — Never commit it to source control or expose it in client-side code.
• Validate every installation request — Always recalculate the hash before trusting any parameters from the installation callback.
• Use HTTPS — Your Installation URL should always use HTTPS to protect the credentials in transit.
• Check required roles — Ensure the installing user has the roles your add-on requires before proceeding.
• Handle re-installation — If a user already has your add-on installed, Nexudus may redirect directly without showing the installation prompt.