> ## Documentation Index
> Fetch the complete documentation index at: https://learn.nexudus.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

<Tabs>
  <Tab title="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.                                                            |
  </Tab>

  <Tab title="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>
    ```

    ```json theme={null}
    {
      "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](/rest-api/apps/post-applications).
  </Tab>
</Tabs>

## 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.

<Tabs>
  <Tab title="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.
  </Tab>

  <Tab title="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:**

    ```json theme={null}
    [
      {
        "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](/rest-api/apps/get-applications).
  </Tab>
</Tabs>

## 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=user@example.com
```

### 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.

<CodeGroup>
  ```csharp C# theme={null}
  // 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();
  }
  ```

  ```javascript Node.js theme={null}
  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
    // ...
  }
  ```
</CodeGroup>

### Generating the authentication token

Once the request is validated, generate the authentication token:

<CodeGroup>
  ```csharp C# theme={null}
  var authToken = MD5Hash(token + secret);
  ```

  ```javascript Node.js theme={null}
  const authToken = crypto.createHash('md5')
    .update(token + secret)
    .digest('hex');
  ```
</CodeGroup>

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

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](/rest-api/apps/) 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 **[support@nexudus.com](mailto: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.