Register and authenticate add-ons

Learn how to register an add-on application in Nexudus, configure its settings, and authenticate API requests using the application key and secret.

Register and authenticate add-ons

This guide explains how to register a new add-on application in Nexudus, configure its installation URL and required roles, and authenticate API requests using your application credentials.

💡 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

Every add-on in Nexudus has two key credentials:

Credential	Description
Application Key	A unique identifier for your add-on. This is generated when you register the application and cannot be changed.
Secret Key	A shared secret used to sign and validate installation requests. Never share this key.

When a customer installs your add-on, Nexudus redirects them to your Installation URL with a set of parameters that your application uses to generate an authentication token. This token then allows your add-on to make API calls on behalf of the customer’s account.

Step 1: Register your add-on

You can register a new add-on application in two ways:

Nexudus Dashboard

1. Sign in to your Nexudus account as an Admin.
2. Navigate to Settings > Add-ons > Manage add-ons.
3. The management page is available at: https://dashboard.nexudus.com/apps/applications/manage
4. Click Create to add a new application.
5. Fill in the required fields:

Field	Description
Name	A display name for your add-on (required).
Short Description	A brief description of what your add-on does (required).
Description	A full HTML description shown during installation.
Installation URL	The URL where Nexudus will redirect users after they approve the installation. This must be a publicly accessible HTTPS endpoint.
Published	Set to true if you want this add-on available in the Nexudus marketplace.
Required Roles	Select the roles that a user must have to install and use this add-on.

REST API

You can also create an application using the REST API. You’ll need admin-level API access.

Create an application:

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]
}

For the full API reference, see Create Application.

Step 2: Retrieve your application credentials

After creating the application, you need to retrieve the Application Key and Secret Key. You can find these in the Dashboard or via the REST API.

Nexudus Dashboard

After creating the application in the Dashboard, your credentials are displayed on the application’s detail page. Navigate to Settings > Add-ons > Manage add-ons, click on your application, and you will see the Application Key and Secret Key listed.

🚨 Important

Never share your Secret Key. If someone obtains your Secret Key, they can impersonate your add-on and access customer data. Store it securely in your application configuration.

REST API

You can also retrieve your application credentials using the REST API.

Get all applications:

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

Response:

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

🚨 Important

Never share your Secret Key. If someone obtains your Secret Key, they can impersonate your add-on and access customer data. Store it securely in your application configuration.

For the full API reference, see Get Applications.

Step 3: Handle the installation callback

When a user installs your add-on, Nexudus redirects them to the Installation URL you configured. The redirect includes several query parameters:

Parameter	Description
a	Your Application Key (unique identifier)
t	A unique token to generate the authentication token
d	A timestamp (DateTime ticks) representing the current time
h	An MD5 hash for request validation
b	The Nexudus subdomain of the account installing the add-on
e	The email of the user installing the add-on

Example redirect URL:

https://myapp.com/install?
a=f36292c02d9c438d98d8c9eb34897c90&
t=c90e30fca71a4c37810a292b99d4d4f2&
d=634963729314011098&
h=785a10afef749b1c26cc3c5eb3989082&
b=subdomain&
e=[e-mail]

Validating the request

Before proceeding, verify the request is genuinely from Nexudus by recalculating the hash:

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.

C#

// 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();
}

Generating the authentication token

Once the request is validated, generate the authentication token:

C#

var authToken = MD5Hash(token + secret);

This authToken is used as the password in Basic Authentication when making API calls.

Step 4: Make authenticated API requests

After installation, your add-on can make API requests using Basic Authentication:

Field	Value
Username	Your Application Key
Password	The generated authentication token (MD5 hash of token + secretKey)

Example request:

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

When a user approves the installation of your add-on, Nexudus performs the following actions behind the scenes:

1. Creates an API access user — A new system user is created with the email format {applicationKey}_{businessId}[e-mail] 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

The following Nexudus entities are involved in the add-on system:

Entity	Description
Applications	Defines the add-on application, including its key, secret, install URL, and required roles.
InstalledApplications	Records when an application is installed in a specific business account, including whether admin approval is required.
MarketPlaceApplications	Tracks applications published to the Nexudus marketplace.
InstalledMarketPlaceApplications	Records installations of marketplace applications.

For the full API reference, see the Apps & Marketplace section.

Submit your application for approval

Once your add-on is ready, follow these steps to submit it for approval to the Nexudus team:

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 [e-mail] 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.