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

# Verify a license from a local app

> How ComfyUI, Omnichar Studio and other local apps check an Omnichar license with its ID and secret, get a short-lived ticket and report usage.

Local apps such as ComfyUI and Omnichar Studio run on the user's own machine and never sign in to Omnichar. To use a licensed character they check the license online with two things the user has:

| | Looks like | Where it comes from |
| - | - | - |
| License ID | `lic_live_...` | The `.char` file: `reserved.license.license_id` in its manifest (the same value as `reserved.license.key`) |
| Secret | `lsk_live_...` | The provider: the share email, or **Characters → Licensed → Local apps** in Omnichar Cloud for the licensee team |

Every license has a secret, whether it was issued to a named team or as a [secret license](https://docs.omnichar.org/api/licenses.md#secret-licenses). The secret is never in the `.char`.

Both calls need no API key. They live on the public API at `https://api.omnichar.org/v1`, so the full paths are `https://api.omnichar.org/v1/licenses/verify` and `https://api.omnichar.org/v1/licenses/usage`.

## 1. Verify

`POST /v1/licenses/verify`

```bash theme={null}
curl -s -X POST https://api.omnichar.org/v1/licenses/verify \
  -H "Content-Type: application/json" \
  -d '{
    "license_id": "lic_live_Q2x8...",
    "secret": "lsk_live_...",
    "char_id": "7f1c2a9e-...",
    "output": "image",
    "model": "flux-2-klein",
    "client": "comfyui",
    "client_version": "1.4.0"
  }'
```

| Field | Meaning |
| - | - |
| `license_id` | The license key, from `reserved.license.license_id`. |
| `secret` | The secret the user entered. Up to 100 characters. |
| `char_id` | The character, from `reserved.license.char_id` in the `.char` (the same as `reserved.provider.char_id`). |
| `output` | `image` or `video`: what the app is about to make. |
| `model` | The model the app will use, up to 80 characters. |
| `client` | Your app: `comfyui` or `omnichar-studio`, or your own short name. Up to 40 characters. |
| `client_version` | Your app's version, up to 40 characters. |

`model`, `client` and `client_version` take letters, digits, spaces and `. _ : / @ + -`. Anything else, or a missing field, answers `422` in the usual [error shape](https://docs.omnichar.org/api/errors.md).

### Valid

`200`:

```json theme={null}
{
  "status": "valid",
  "ticket": "lvt_9Jm2...",
  "ttl_seconds": 600,
  "valid_until": "2026-11-15T10:25:00.000Z",
  "owner_name": "Omnicast Talents"
}
```

`ticket` is an opaque string for [reporting usage](#2-report-usage). Omnichar keeps only its hash. It lasts `ttl_seconds`, 600, or less when the license ends sooner; `valid_until` is when it stops, the earlier of the two. `owner_name` is the provider team's name, to show the user whose character it is.

Verify again for a new ticket when this one runs out. Verifying does not count as a generation; only usage reports do.

### Refused

`403`, with a `status` to branch on and a `message` you can show the user as it is:

| `status` | `message` |
| - | - |
| `wrong_secret` | The license ID or secret is not right. Check the secret you were given. |
| `revoked` | This license was revoked by Omnicast Talents. |
| `expired` | This license expired on 12 March 2027. |
| `not_started` | This license starts on 1 December 2026. |
| `wrong_character` | This license is for a different character. |
| `output_not_allowed` | This license does not allow video. |
| `limit_reached` | This license has used all of its generations. Ask Omnicast Talents for more. |

Messages name the real provider and dates; branch on `status`, not on `message`, which can change. These bodies are not the usual `{"error": ...}` shape.

The checks run in this order, so nothing about a license is said until the secret is right:

1. The secret matches the license. A `lsk_test_` secret only verifies a sandbox license and a `lsk_live_` secret only a production one. An unknown license ID gets the same `wrong_secret` as a wrong secret.
2. The license is not revoked.
3. It has not expired.
4. It has started (`starts_at`). A license named by an email that has not signed up yet works here: the secret is the credential.
5. `char_id` is the license's character.
6. `output` is in the license's `scope.media`.
7. If `scope.max_generations` is set, it has not been reached.

`use`, `territories` and `allow_list` are not checked here: a local app has no team or run context to check them against.

When a check after the secret fails, the provider sees it as a blocked [usage](https://docs.omnichar.org/api/usage.md#local-use) record and gets `usage.blocked`, at most once a minute per license and reason.

### Too many wrong secrets

After 5 wrong secrets for one license ID in 15 minutes, or 20 from one address for any license IDs, further wrong secrets for that license ID or from that address answer `429` until the 15 minutes pass. The right secret always gets through, so someone sending junk with a license ID from a `.char` cannot lock out the people it belongs to. The body is the usual error shape with the code `rate_limited`, and `retry-after` says how many seconds to wait. License IDs that do not exist lock the same way, so a lockout says nothing about whether a license is real. An IPv6 address counts by its /64.

The route also allows 30 verify calls a minute per address, whatever the answer; over that you get the same `429` shape.

## 2. Report usage

`POST /v1/licenses/usage`

Report each generation once it is made:

```bash theme={null}
curl -s -X POST https://api.omnichar.org/v1/licenses/usage \
  -H "Content-Type: application/json" \
  -d '{ "ticket": "lvt_9Jm2...", "output": "image", "model": "flux-2-klein", "client": "comfyui" }'
```

`202` with `{"accepted": true}`. The report becomes a usage record the provider sees on its dashboard and in [usage](https://docs.omnichar.org/api/usage.md#local-use), with `"surface": "local"`, `"team_id": null` and the `model`, `client` and `client_version` you sent, and the provider gets `usage.generated`. If the license has `scope.max_generations`, each report counts against it, as a Cloud run does.

| Status | Body `status` | When |
| - | - | - |
| `401` | `invalid_ticket` | The ticket is unknown or past `valid_until`, the license was revoked or has ended since the ticket was given, or its secret was rotated. Verify again. |
| `403` | `output_not_allowed` | `output` is not the one the ticket was verified for, and the license does not allow it. |
| `403` | `limit_reached` | The license has used all of `scope.max_generations`. |
| `429` | `invalid_ticket` | The ticket has made 200 reports. Verify again for a new one. |
| `429` | | Over 120 usage calls a minute from one address. This one uses the usual error shape with the code `rate_limited` and a `retry-after` header. |

Refusals with a `status` use the same `{"status": ..., "message": ...}` shape as verify.

## Rotation and revocation

When the provider [rotates the secret](https://docs.omnichar.org/api/licenses.md#rotate-the-secret), the old one answers `wrong_secret` at once and every ticket it was given stops working. When the provider revokes the license, its tickets stop working too, and verify answers `revoked`. Ask the user for the new secret, or tell them the license has ended.

## Building a client

* Ask the user for the secret once and store it as a secret, never in a workflow file, a log or an output.
* Read `license_id` and `char_id` from the `.char` the user loaded; do not ask for them.
* Verify before the first generation and again once `valid_until` passes.
* Show the `message` from a refusal; it is written for the user.
* On `429`, wait for `retry-after` before asking again.


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