License and Tiers

SelfDocHub requires a signed license file for each installation. This page explains how a license is tied to an installation, how to install it and what each tier allows.

Roles: Only an admin can upload a license. Everyone can open the license status screen, which shows only the device ID and dates.

How a license works#

  • A license is tied to one installation's device ID: a random identifier generated once and stored in the data directory. It stays the same across restarts as long as the same persistent volume is reused.
  • The license file (license.json) is signed. The application can verify a license but can never issue one. Editing the file invalidates it.
  • The file records the customer, tier, validity dates and the final value of every feature, limit and quota.
  • The license is re-verified from disk every 15 minutes.

Getting a license#

  1. Print the device ID of the installation:

    docker compose exec docs-hub docs-hub --print-device-id
    

    The device ID is also shown on the License page.

  2. Request a license for that device ID from your account on this site. See the FAQ for how plans and issuance quotas work.

  3. Install the resulting license.json.

Installing a license#

  • In the UI. Sign in as an administrator, open License in the top menu, paste the contents of license.json and save.

  • Through the API. Send the file with an administrator session token:

    curl -X POST http://localhost:8080/api/v1/admin/license \
      -H "Authorization: Bearer <admin session token>" \
      -H "Content-Type: application/json" \
      --data-binary @license.json
    
  • Before the first start. Place license.json in the data directory.

A valid upload takes effect immediately, with no restart.

To get renewed licenses without uploading files, set up Automatic License Renewal.

Without a valid license#

The server still starts. Sign-in, the License page and the interface translations keep working, but every other /api/v1/* route returns 402 Payment Required. The web UI then shows a full-page "No valid license found" screen with the device ID and dates, and an upload form for administrators. For limit checks an unlicensed installation behaves like the Free tier.

Tiers#

Free (personal) Team Business Unlimited
Users / teams 2 / 1 20 / 3 100 / 30 no limit
Services 3 15 200 no limit
Endpoints per service 50 300 3000 no limit
MCP server 1 token, 20 000 requests/month 5 tokens, 100 000 requests/month 20 tokens, 500 000 requests/month yes
Try-It through MCP no no yes, 10 000 requests/month yes
SSO no no yes yes
Notifications no yes yes yes
Export 20/month 200/month 2 000/month yes
Try-It yes yes yes yes

A license can also be issued with custom features, limits and quotas, so the License page is the authoritative view of what your installation allows. It shows the features, each limit with current usage, and each quota with its usage in the current window and reset date. Quotas use calendar windows in UTC (hour, day, week or month).

What happens at a limit#

  • Only creating more is refused: the API answers 402 with code: "license_limit".
  • Existing data is never deleted or hidden, so a downgrade stops growth without losing anything.
  • The MCP endpoint answers 404 when MCP is not licensed and 429 when its request quota is spent.
  • The endpoint limit counts the operations, methods or fields of an uploaded specification and rejects the publish before anything is saved.
  • An export that fails validation is not charged to the quota.

A license.json issued before limits existed (without a version field) is accepted and means unlimited.

Expiry warnings#

An administrator can be warned before the license ends. See Notifications.

Next steps#

Screenshots

Last updated: