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

# BuiltByBit License Placeholder Integration

> Automatically issue and insert Avalex license keys into resource files when buyers download from BuiltByBit.

Avalex includes native support for BuiltByBit's **External License Key Placeholders**. When a buyer downloads your resource on BuiltByBit, BuiltByBit automatically sends a webhook request to your Avalex server. Avalex securely generates or retrieves the buyer's license key and responds immediately — allowing BuiltByBit to inject the license key directly into the downloaded file before delivery.

```mermaid theme={null}
sequenceDiagram
    autonumber
    actor Buyer as Buyer
    participant BBB as BuiltByBit
    participant Avalex as Avalex Server
    Buyer->>BBB: Downloads Resource
    BBB->>Avalex: POST /builtbybit (user_id, resource_id, secret)
    Note over Avalex: 1. Verify Secret<br/>2. Match Product by Resource ID<br/>3. Resolve or Create Customer<br/>4. Idempotently Issue / Reuse License
    Avalex-->>BBB: 200 OK (Plain Text: License Key)
    BBB->>Buyer: Injects key into placeholder & delivers file
```

***

## How It Works

1. **Secret Verification**: When BuiltByBit calls your webhook, it includes a configured shared secret. Avalex compares this with the secret defined in your backend configuration.
2. **Product Matching**: Avalex matches the incoming `resource_id` against the **BuiltByBit Resource ID** set on your products.
3. **Customer Resolution**: Avalex checks if a customer with the buyer's BuiltByBit ID (`socials.BuiltByBitID`) already exists:
   * **Existing customer**: The license is assigned directly to them.
   * **New customer**: A new customer profile is automatically created using their BuiltByBit User ID (and Steam ID if available).
4. **Double-License Prevention (Idempotent)**: If the buyer already holds an active, non-expired license for that product, Avalex re-returns the existing license key without generating unnecessary duplicate licenses or orders.
5. **Automated Order & License Creation**: If the buyer has no active license, Avalex generates a new license key (inheriting IP and HWID slot limits and subscription duration from the product) and creates an order record.
6. **Instant Plain Text Delivery**: Avalex returns only the license key string as plain text (`text/plain`), which BuiltByBit embeds at your placeholder's token location.

***

## Step-by-Step Setup

<Steps>
  <Step title="Configure your BuiltByBit Secret in Avalex">
    In your server configuration (`application.conf` or environment variable `BUILTBYBIT_SECRET`), set a strong secret token:

    ```hocon theme={null}
    builtByBit {
      secret = "your-strong-random-secret"
    }
    ```

    Or set the environment variable:

    ```bash theme={null}
    export BUILTBYBIT_SECRET="your-strong-random-secret"
    ```
  </Step>

  <Step title="Map BuiltByBit Resource ID to your Product">
    Open the **Avalex Admin Portal**, navigate to **Products**, edit or create the product you are selling, and set the **BuiltByBit Resource ID** (e.g. `98765`).
  </Step>

  <Step title="Create a Placeholder on BuiltByBit">
    1. Log in to [BuiltByBit](https://builtbybit.com) and go to your resource management dashboard.
    2. Navigate to **Placeholders** (`builtbybit.com/placeholders/`).
    3. Click **Create Placeholder** and set the **Type** to `External license key`.
    4. Set the **Server URL** to your Avalex public endpoint:
       ```text theme={null}
       https://api.yourdomain.com/builtbybit
       ```
    5. Enter the exact **Secret** you configured in Step 1.
  </Step>

  <Step title="Add the Placeholder Token to your Resource Files">
    Drop the placeholder token provided by BuiltByBit (e.g. `%%__LICENSE_KEY__%%` or your custom token) inside your plugin configuration, source code, or licensing files.
  </Step>
</Steps>

***

## Webhook Request Specifications

BuiltByBit sends an HTTP `POST` request with form data (`application/x-www-form-urlencoded` or `multipart/form-data`) containing:

| Parameter | Type | Description |
| - | - | - |
| `secret` | string | The shared secret configured in BuiltByBit and Avalex. |
| `user_id` | string | The BuiltByBit User ID of the buyer downloading the resource. |
| `resource_id` | string | The BuiltByBit Resource ID being downloaded. |
| `builtbybit` | string | Fixed flag sent by BuiltByBit (typically `true`). |
| `steam_id` | string | Optional Steam64 ID of the buyer (if linked on BuiltByBit). |
| `version_id` | string | Optional internal resource version identifier. |
| `version_number` | string | Optional release version tag (e.g. `1.0.4`). |

***

## Response Format

Avalex responds with `200 OK` and Content-Type `text/plain; charset=UTF-8`:

```http theme={null}
HTTP/1.1 200 OK
Content-Type: text/plain; charset=UTF-8

9F2K-8A3M-7P1Q-4W6R
```

<Note>
  Whatever string Avalex returns is inserted directly at the placeholder's location in the downloaded file.
</Note>

***

## Security & Reliability Features

* **Rate Limiting**: The endpoint is protected with a rate limiter allowing up to **60 requests per minute** per IP.
* **Audit Logging**: Every issuance (`builtbybit.license.create`), reuse (`builtbybit.license.reuse`), and rejection (`builtbybit.license.reject`) is recorded in the Avalex audit log with the associated user ID and resource ID.
* **Automatic Fallback Protection**: If the secret is missing or misconfigured on the server, requests are automatically rejected to prevent unauthorized license generation.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.