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

   ```bash
   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:

  ```bash
  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](/documentation/license-auto-renew).

## 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](/documentation/notifications).

## Next steps

- [Automatic License Renewal](/documentation/license-auto-renew)
- [Installation](/documentation/installation)
- [Notifications](/documentation/notifications)

---
Source: https://selfdochub.com/documentation/license
