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

# BuiltByBit Integration

> Lukittu supports BuiltByBit by providing a fully automatic licensing experience for your resources.

# BuiltByBit Integration

<Note>
  Lukittu automatically delivers licenses to your customers when they purchase
  through BuiltByBit.
</Note>

## Implementation Overview

Follow these steps to configure licensing for the products you sell using BuiltByBit:

<Steps>
  <Step title="Create a product in Lukittu">
    First, set up your product in the Lukittu platform.
  </Step>

  <Step title="Enable the BuiltByBit integration">
    Activate the integration in your Lukittu dashboard.
  </Step>

  <Step title="Set up a purchase webhook">
    Configure BuiltByBit to notify Lukittu of purchase events.
  </Step>

  <Step title="Create a license placeholder">
    Set up automatic license delivery for your customers.
  </Step>
</Steps>

## Creating a Product in Lukittu

<Steps>
  <Step title="Navigate to Products">
    Go to the **Products** page in your Lukittu dashboard and click **Add
    Product**.
  </Step>

  <Step title="Add product details">
    Enter a name for your product and click **Save**.
  </Step>

  <Step title="Get the product ID">
    Open the page for your newly created product and copy the product's
    **ID**.
    <Tip>You'll need this ID when configuring your BuiltByBit webhook.</Tip>
  </Step>
</Steps>

## Enabling BuiltByBit Integration

Before setting up webhooks on BuiltByBit, you need to enable the integration in your Lukittu dashboard:

<Steps>
  <Step title="Access Integrations Settings">
    Log in to your Lukittu dashboard and navigate to the **Integrations**
    tab.
  </Step>

  <Step title="Enable the Integration">
    Locate the BuiltByBit integration option and toggle it to **Active**.
  </Step>

  <Step title="Copy the Secret">
    Copy the generated **Secret** as you'll need it for the webhook setup.

    <Info>
      Keep this secret secure as it authenticates your webhook requests.
    </Info>
  </Step>
</Steps>

## Setting Up Purchase Webhook

Follow these steps to configure the purchase webhook that will automatically issue licenses:

<Steps>
  <Step title="Access BuiltByBit Webhooks">
    Go to the [BuiltByBit webhooks dashboard](https://builtbybit.com/resources/dashboard/webhooks) and click the **Create webhook** button.
  </Step>

  <Step title="Configure Webhook Settings">
    Enter a descriptive name for the webhook. Select **Purchase** from the Trigger dropdown. Choose **Only apply to certain resources** and select the specific resource(s) you want to license.
  </Step>

  <Step title="Set Webhook URL">
    Enter the following URL:

    ```
    https://app.lukittu.com/api/v1/integrations/built-by-bit?teamId=YOUR_TEAM_ID
    ```

    Replace `YOUR_TEAM_ID` with your Lukittu team's ID.

    <Info>
      To find your Team ID, go to the Lukittu dashboard and navigate to
      **Team** → **Settings**.
    </Info>
  </Step>

  <Step title="Configure Webhook Format">
    Select **Custom** for Template, **POST** for Method, and **application/json** for Content Type.
  </Step>

  <Step title="Set Webhook Body">
    Copy and paste the following JSON template:

    ```json theme={null}
    {
        "apiSecret": "YOUR_BUILT_BY_BIT_SECRET",
        "builtByBitData": {
            "user": {
                "id": "{user_id}",
                "username": "{username}",
                "userUrl": "{user_url}"
            },
            "resource": {
                "title": "{resource_title}",
                "id": "{resource_id}",
                "url": "{resource_url}",
                "addon": {
                    "id": "{addon_id}",
                    "title": "{addon_title}"
                },
                "bundle": {
                    "id": "{bundle_id}",
                    "title": "{bundle_title}"
                },
                "renewal": "{renewal}",
                "pricing": {
                    "listPrice": "{list_price}",
                    "finalPrice": "{final_price}"
                },
                "purchaseDate": "{purchase_date}"
            }
        },
        "lukittuData": {
            "productId": "YOUR_LUKITTU_PRODUCT_ID",
            "ipLimit": null,
            "hwidLimit": null,
            "expirationDays": null,
            "expirationStart": null
        }
    }
    ```
  </Step>

  <Step title="Customize Webhook Data">
    Replace `YOUR_BUILT_BY_BIT_SECRET` with the integration secret from your Lukittu dashboard. Replace `YOUR_LUKITTU_PRODUCT_ID` with the product ID you copied earlier.

    <Note>
      The fields `ipLimit`, `hwidLimit`, `expirationDays`, and `expirationStart` are optional configuration parameters. Leave them as `null` if you don't need them, or set appropriate values based on your licensing requirements.
    </Note>
  </Step>

  <Step title="Save the Webhook">
    Click the **Save** button to create your purchase webhook.
  </Step>
</Steps>

### Optional License Configuration

The following parameters can be customized in the webhook JSON:

| **Key**           | **Type**                   | **Description**                                                                                  |
| ----------------- | -------------------------- | :----------------------------------------------------------------------------------------------- |
| `ipLimit`         | Number                     | Maximum number of IPs allowed.                                                                   |
| `hwidLimit`       | Number                     | Number of concurrent users allowed.                                                              |
| `expirationDays`  | Number                     | Number of days until the license expires.                                                        |
| `expirationStart` | `ACTIVATION` or `CREATION` | Determines when expiration starts (default: `CREATION`). Applicable if `expirationDays` is used. |

## Setting Up License Placeholder

To enable automatic license delivery to your customers, you need to create a license placeholder:

<Steps>
  <Step title="Access BuiltByBit Placeholders">
    Go to the [BuiltByBit placeholders
    page](https://builtbybit.com/placeholders/) and click the **Create
    placeholder** button.
  </Step>

  <Step title="Configure Placeholder Settings">
    Enter a descriptive placeholder name (e.g.,
    `%%__LUKITTU_LICENSE_KEY__%%`). Select **External license key** from the
    Type dropdown.
  </Step>

  <Step title="Set Placeholder URL">
    Enter the following URL: `         https://app.lukittu.com/api/v1/integrations/built-by-bit/placeholder?teamId=YOUR_TEAM_ID
                ` Replace `YOUR_TEAM_ID` with your Lukittu team's ID.
  </Step>

  <Step title="Set Secret">
    Enter the BuiltByBit integration secret you created on your Lukittu
    dashboard.
  </Step>

  <Step title="Save the Placeholder">
    Click the **Save** button to create your license placeholder.
  </Step>
</Steps>

## Manually Assigning BuiltByBit Licenses (Without a Purchase)

In some cases, you may want to grant a BuiltByBit user access to one of your products even if they have not purchased it through BuiltByBit. Lukittu fully supports this by allowing you to manually attach the required BuiltByBit metadata to a license.

When BuiltByBit processes a real purchase, it automatically sends the `BBB_USER_ID` and `BBB_RESOURCE_ID` values to Lukittu. If no purchase exists, you can add these values manually to any license you create.

### How It Works

To manually link a license to a BuiltByBit user and resource:

1. Set the following metadata fields on the license:

   * **`BBB_USER_ID`** — The BuiltByBit user ID
   * **`BBB_RESOURCE_ID`** — The BuiltByBit resource ID

2. Once these metadata fields are present, **Lukittu treats the license exactly as if it were generated through a BuiltByBit purchase**.
   This means:

   * The license will correctly inject into BuiltByBit placeholders
   * All automation behaves normally

### Finding the Required IDs

You can obtain both IDs directly from BuiltByBit URLs.

#### Resource ID

This is the numeric portion at the end of the resource URL:
Example:
`https://builtbybit.com/resources/lukittu-license-system-open-source.62494`
Resource ID: **62494**

#### User ID

This is the numeric portion at the end of a user profile URL:
Example:
`https://builtbybit.com/members/kasperi.540773`
User ID: **540773**

### Summary

If you need to assign a license to a BuiltByBit user without a purchase, simply add `BBB_USER_ID` and `BBB_RESOURCE_ID` as metadata to the Lukittu license. Once added, the license will fully support BuiltByBit placeholder injection and behave identically to automatically issued licenses.

## Verifying the Integration

<Accordion title="Testing Your Integration">
  * **Make a Test Purchase** - Make a test purchase of your resource on
    BuiltByBit. You can use a coupon to get it for free! - **Verify License
    Generation** - Check that a license is automatically generated in your
    Lukittu dashboard after the purchase. - **Confirm License Delivery** -
    Verify that the license key is correctly replacing the corresponding
    placeholder during download.
</Accordion>