Every license has a secret, whether it was issued to a named team or as a secret license. 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
model, client and client_version take letters, digits, spaces and . _ : / @ + -. Anything else, or a missing field, answers 422 in the usual error shape.
Valid
200:
ticket is an opaque string for reporting 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:
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:
- The secret matches the license. A
lsk_test_secret only verifies a sandbox license and alsk_live_secret only a production one. An unknown license ID gets the samewrong_secretas a wrong secret. - The license is not revoked.
- It has not expired.
- It has started (
starts_at). A license named by an email that has not signed up yet works here: the secret is the credential. char_idis the license’s character.outputis in the license’sscope.media.- If
scope.max_generationsis 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 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 answer429 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:
202 with {"accepted": true}. The report becomes a usage record the provider sees on its dashboard and in usage, 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.
Refusals with a
status use the same {"status": ..., "message": ...} shape as verify.
Rotation and revocation
When the provider rotates the secret, the old one answerswrong_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_idandchar_idfrom the.charthe user loaded; do not ask for them. - Verify before the first generation and again once
valid_untilpasses. - Show the
messagefrom a refusal; it is written for the user. - On
429, wait forretry-afterbefore asking again.