# RightOS — Full Documentation for AI Agents and Developers

Last updated: 2026-07-09 (Outbound webhooks with HMAC-SHA256-signed deliveries; Policy Engine — country overlays expanded to 10 countries with public GET /api/rightos/policies — plus holder self-cancel, policy audit log, Stripe billing, and official TypeScript/Python SDKs). Authoritative sources: this file, https://rightos.i-s3.com/openapi.json, and the pages under https://rightos.i-s3.com/software/rightos. Legal texts are authoritative in Japanese and English.

## 1. What RightOS is

RightOS is a privacy-preserving rights verification infrastructure operated by I-S3 Inc. (Gunma, Japan). It turns everyday receptions — queues, reservations, EV charging slots, package pickups — into digital QR tickets called **Right Tokens**.

The core design principle: verify that **a valid right is present**, not **who the person is**.

- End users never need to provide a name, phone number, or birthdate.
- No app install: tickets are web pages (Right Wallet) that display a QR code.
- Operators verify by scanning the QR with a camera (processed on-device, never uploaded) or by entering the token ID and code manually.

### What RightOS is NOT

RightOS is not a taxi or ride-hailing service. It does not arrange vehicles, set fares, assign drivers, or broker dispatch. At taxi stands or pickup zones it only verifies waiting order and access rights. This is a firm product boundary, stated in the Terms of Service (prohibited uses include brokering passenger transport).

## 2. Core concepts

- **Right Token**: a digital right (queue position, time slot, usage right). Identified by `tokenId` (e.g. tok_2f8a...). Status: issued → verified → used, or cancelled / expired.
- **verificationCode**: a secret handed to the holder exactly once at issuance (e.g. K7MP-Q2XT9). The server stores only its SHA-256 hash (`secretHash`). Possession of the code = possession of the right.
- **Right Wallet**: the end-user page displaying the QR (wallet URL contains tokenId + code). Whoever holds the link holds the right.
- **Verify**: hash-comparison of the presented code. Results: `success`, `failed`, `expired`, `cancelled`, `already_used`. Every attempt is logged.
- **Transfer (re-keying)**: only the current holder (who knows the current code) can transfer. A new code is issued; the old one is invalidated immediately. `transferCount` is recorded. Paid transfers and auctions are deliberately not offered (resale/regulatory risk).
- **Organization**: a business account with an API key (`rk_live_...`), plan, and locations.
- **Location**: a place where rights are issued/verified (shop, clinic, ev_charging, event, logistics, pickup, other).
- **Policy** (Phase 2): per-location rules — transferability, max transfer count, default validity, identity-check delegation, and holder self-cancellation. Resolution order: industry preset (by location type) -> country overlay (organization country x location type; conservative operational defaults, not legal advice — e.g. JP events default to a single companion transfer, reflecting Japan's ticket resale law; overlays currently cover JP, US, GB, KR, TW, FR, DE, IT, ES, AU, informed by e.g. South Korea's 2026 Performance Act amendment, France's Penal Code art. 313-6-2, Italy's 2016 Budget Law anti-secondary-ticketing rules) -> per-location override. The full policy knowledge base (all presets and overlays) is public via GET /api/rightos/policies. Each location type has an industry preset (e.g. clinic and ev_charging are non-transferable; event and pickup allow exactly one transfer; event/logistics/pickup disallow holder self-cancel by default). Operators can override per location. Effective policy is public via GET /api/rightos/locations/{locationId}/policy for transparency. Transfers rejected by policy return HTTP 409 with error codes policy_transfer_disabled or transfer_limit_reached; self-cancel rejected by policy returns 409 policy_cancel_disabled. All policy override changes are recorded in an append-only audit log (GET /api/rightos/locations/{locationId}/policy/history, own organization only; also included in data export).

## 3. Quickstart (10 minutes)

1. Register: POST https://rightos.i-s3.com/api/rightos/organizations
   Body: {"name":"My Shop","contactEmail":"you@example.com","planId":"free"}
   → The response contains your API key (rk_live_...) EXACTLY ONCE. Store it securely.
2. Create a location (or use the one created for you):
   POST /api/rightos/locations  (Authorization: Bearer rk_live_...)
   Body: {"name":"Main counter","type":"shop"}
3. Issue a ticket:
   POST /api/rightos/tokens/issue  (auth required)
   Body: {"locationId":"loc_...","title":"Queue ticket"}
   → Response has verificationCode + walletUrl (shown once). Hand the walletUrl QR to your customer.
4. Verify on arrival:
   POST /api/rightos/tokens/{tokenId}/verify  (no auth)
   Body: {"verificationCode":"..."}
   → {"result":"success", "token":{...}}
5. Mark as used:
   POST /api/rightos/tokens/{tokenId}/use  (auth required)

Or do all of this in the browser: Console (https://rightos.i-s3.com/software/rightos/console) for issuing, adding locations (with a live preview of the policy defaults for your country and location type), reviewing the verification log (latest 20 attempts, no personal data), and managing policies; Verify screen (https://rightos.i-s3.com/software/rightos/verify) with camera QR scanning, including a kiosk mode for continuous back-to-back scanning at entrances (optional auto mark-as-used with the organization's API key; all video is processed on-device and never uploaded). For a guided 60-second hands-on demo (issue a real ticket on the shared demo org, then verify it), see https://rightos.i-s3.com/software/rightos/demo

Live demo without registration:
- Wallet: https://rightos.i-s3.com/software/rightos/wallet/tok_demo_queue?code=DEMO-QUEUE234
- Verify: https://rightos.i-s3.com/software/rightos/verify?tokenId=tok_demo_queue&code=DEMO-QUEUE234
- Console demo key: rk_demo_00000000000000000000 (shared, resets periodically, cannot be rotated or deleted)

## 3b. Official SDKs (TypeScript / Python)

Zero-dependency clients, also distributed as single files you can download and drop into your project:
- TypeScript: npm install @i-s3/rightos (https://www.npmjs.com/package/@i-s3/rightos) or single file https://rightos.i-s3.com/sdk/rightos.ts (Node.js >= 18 and browsers, fetch-based, fully typed)
- Python: pip install rightos-sdk (https://pypi.org/project/rightos-sdk/) or single file https://rightos.i-s3.com/sdk/rightos.py (Python >= 3.9, standard library only)
- Source repository (MIT): https://github.com/suomimasuda/rightos-sdk

TypeScript example:
    import { RightOS } from "./rightos";
    const client = new RightOS({ apiKey: "rk_live_..." });
    const [location] = await client.listLocations();
    const issued = await client.issueToken({ locationId: location.id, title: "Queue ticket" });
    const outcome = await RightOS.verify(issued.token.id, issued.verificationCode); // { result: "success" }
    await client.useToken(issued.token.id);

Python example:
    from rightos import RightOS
    client = RightOS(api_key="rk_live_...")
    location = client.list_locations()[0]
    issued = client.issue_token(location_id=location["id"], title="Queue ticket")
    outcome = RightOS().verify_token(issued["token"]["id"], issued["verificationCode"])  # {"result": "success"}
    client.use_token(issued["token"]["id"])

MCP server for AI agents (@i-s3/rightos-mcp on npm): run with `npx -y @i-s3/rightos-mcp` (stdio transport). Set the RIGHTOS_API_KEY environment variable (rk_live_...) for operator tools; without it, public tools still work. 18 tools: list_plans, get_token, verify_token, transfer_token, holder_cancel_token, get_location_policy, list_policies (public) + list_locations, create_location, set_location_policy, issue_token, use_token, cancel_token, get_policy_history, export_data, list_webhooks, create_webhook, delete_webhook (operator). Example client config:
    { "mcpServers": { "rightos": { "command": "npx", "args": ["-y", "@i-s3/rightos-mcp"], "env": { "RIGHTOS_API_KEY": "rk_live_..." } } } }

Human quickstart page (registration to verified ticket in 10 minutes): https://rightos.i-s3.com/software/rightos/docs/quickstart

Both SDKs throw/raise RightOSError with `status` (HTTP), `code` (API error code such as policy_transfer_disabled, policy_cancel_disabled, transfer_limit_reached, rate_limited), and retry-after seconds on 429. SDK method names (v0.2.0+): holderCancelToken/holder_cancel_token and getLocationPolicyHistory/get_location_policy_history cover the Policy Phase 2 endpoints. Full list: listPlans/list_plans, getToken/get_token, verifyToken/verify_token, transferToken/transfer_token, holderCancelToken/holder_cancel_token, getLocationPolicy/get_location_policy, getLocationPolicyHistory/get_location_policy_history, registerOrganization/register_organization, listLocations/list_locations, createLocation/create_location, setLocationPolicy/set_location_policy, issueToken/issue_token, useToken/use_token, cancelToken/cancel_token, exportData/export_data, rotateApiKey/rotate_api_key, deleteOrganization/delete_organization. v0.4.1 adds webhook delivery observability fields on listWebhooks/list_webhooks responses (lastDelivery, deliveredCount, failedCount). v0.4.0 adds webhook support: listWebhooks/list_webhooks, createWebhook/create_webhook, deleteWebhook/delete_webhook, and a signature verification helper (TypeScript: static RightOS.verifyWebhookSignature(secret, signatureHeader, rawBody); Python: rightos.verify_webhook_signature(secret, signature_header, raw_body)) implementing the t=<unix seconds>,v1=<hex HMAC-SHA256> scheme with replay protection.

## 4. Authentication

- Operator endpoints require the API key issued once at registration.
- Send as `Authorization: Bearer rk_live_...` or `x-rightos-key: rk_live_...`.
- The server stores only the key's SHA-256 hash and can never re-display it.
- Rotation: POST /api/rightos/organizations/rotate-key (requires current key; old key invalidated immediately).
- Lost key: manual re-issue via I-S3 support after verifying the registered email.

## 5. API reference (summary)

Machine-readable spec: https://rightos.i-s3.com/openapi.json (OpenAPI 3.1)

Public (no auth):
- GET  /api/rightos/status — service status: self-checks + measured uptime 24h/7d/30d (human page: /software/rightos/status)
- GET  /api/rightos/plans — pricing plans
- GET  /api/rightos/tokens/{tokenId} — token details (never includes secretHash)
- GET  /api/rightos/locations/{locationId}/policy — effective location policy (transparency)
- GET  /api/rightos/policies — all industry presets and country overlays (the policy knowledge base; defaults, not legal advice)
- POST /api/rightos/tokens/{tokenId}/verify — verify a code (rate limited)
- POST /api/rightos/tokens/{tokenId}/transfer — transfer via re-keying (rate limited)
- POST /api/rightos/tokens/{tokenId}/holder-cancel — self-cancel by the current holder using the verificationCode (409 policy_cancel_disabled when the location's policy forbids it; rate limited)
- POST /api/rightos/organizations — register (returns API key once; rate limited)

Billing (Stripe hosted Checkout / Billing Portal; card data never touches RightOS servers):
- GET  /api/rightos/billing/config — whether billing is enabled (public)
- POST /api/rightos/billing/checkout — create a Checkout session for starter/business/pro (auth; 503 when billing is disabled = MVP mode)
- POST /api/rightos/billing/portal — Billing Portal for payment methods and cancellation (auth)
- Cancelling downgrades to free; data is never deleted.

Authenticated (API key):
- POST /api/rightos/tokens/issue — issue a ticket (402 over plan limit)
- POST /api/rightos/tokens/{tokenId}/use — mark used (own org only)
- POST /api/rightos/tokens/{tokenId}/cancel — cancel (own org only)
- GET/POST /api/rightos/locations — list/create locations (402 over plan limit)
- PUT  /api/rightos/locations/{locationId}/policy — override location policy (partial; null resets to preset; changes are audit-logged)
- GET  /api/rightos/locations/{locationId}/policy/history — policy change audit log (own org only)
- GET  /api/rightos/console — dashboard data (includes usage vs. plan limits and webhooks)
- GET  /api/rightos/export — full data export (JSON, no secrets)
- POST /api/rightos/organizations/rotate-key — re-issue API key
- POST /api/rightos/organizations/delete — permanent deletion (body.confirm = exact org name)
- GET  /api/rightos/webhooks — list webhooks (never includes signing secrets; each webhook includes lastDelivery {at, event, ok, status?, error?} and deliveredCount/failedCount for observability)
- POST /api/rightos/webhooks — register a webhook (up to 3 per org; https only; 400 for internal/private hosts)
- DELETE /api/rightos/webhooks/{webhookId} — delete a webhook

Outbound webhooks:
- Events: token.verified, token.used, token.cancelled (operator cancel and holder self-cancel), token.transferred.
- Payload: {"id": "evt_...", "type": "<event>", "createdAt": "<ISO 8601>", "data": {"token": {...}}} — never contains secret values.
- Signature: header `x-rightos-signature: t=<unix seconds>,v1=<hex>` where v1 = HMAC-SHA256(signing secret, `${t}.${raw request body}`). Verify by recomputing.
- The signing secret (whsec_...) is returned exactly once at registration and is NOT stored on RightOS servers (derived from a master key).
- Delivery is best-effort: 3s timeout, no retries. Respond 2xx immediately; process asynchronously.

## 6. Limits

Rate limits (HTTP 429 + Retry-After):
- verify / transfer: 10 requests/min per IP+token, 60/min per IP (brute-force protection for the ~40-bit code)
- organization registration: 5/hour per IP

Plan limits (HTTP 402):
- free: 50 tokens/month, 1 location
- starter (¥2,980/mo): 1,000 tokens/month, 3 locations
- business (¥9,800/mo): 10,000 tokens/month, 20 locations
- pro (¥29,800/mo): 100,000 tokens/month, unlimited locations
- enterprise: custom
Prices are globally uniform (same everywhere, JPY). During the MVP period no credit card is required.

## 7. Error model

JSON body: {"error": "<code>", "message": "<optional detail>"}
Common codes: missing_api_key, invalid_api_key (401); plan limit (402); demo_org / ownership violation (403); not_found (404); confirmation_required (400); rate_limited (429).

## 8. Privacy and security design

- No personal data required from end users by design (names/phones/birthdates never mandatory).
- Secrets (verificationCode, API keys) are stored only as SHA-256 hashes.
- QR codes contain only tokenId + verificationCode.
- Camera QR scanning runs fully on-device (BarcodeDetector or jsQR); video is never uploaded. Browser permission can be revoked at any time.
- IP addresses are used transiently in memory for rate limiting only.
- Data stored on Google Cloud (Tokyo region), TLS in transit, 30-day versioned backups.
- Data portability: self-service full export and permanent deletion (see §5).
- Security headers: CSP, HSTS, nosniff, frame-ancestors none.
- Roadmap: challenge-signature verification with device key pairs (WebCrypto / passkeys) to supersede code presentation.

## 9. Typical use cases

- Retail / restaurants: queue tickets — customers wait outside or in their car.
- Clinics: call-order management without collecting patient identities at the queue layer.
- EV charging: time-slot rights for chargers; verify the right, not the person, at the plug.
- Package pickup: hand the wallet URL to the recipient; whoever presents the valid code receives the package.
- Events: entry rights with transfer support (re-keying) and no resale/auction mechanics.
- Taxi stands / pickup zones: waiting-order verification ONLY (no dispatch, no fare, no driver assignment).

## 10. Internationalization

- UI: 20 languages (ja, en, zh-CN, zh-TW, ko, es, fr, de, it, pt, ru, ar, hi, th, vi, id, tr, nl, pl, sv). Arabic renders RTL.
- Explainer video: audio in Japanese and English; subtitles in all 20 languages.
- Legal documents (Privacy Policy, Terms) are authoritative in Japanese and English; other UI languages fall back to English.

## 11. Legal and company

- Terms of Service: https://rightos.i-s3.com/software/rightos/legal/terms (Japanese law, Maebashi District Court)
- Privacy Policy: https://rightos.i-s3.com/software/rightos/legal/privacy
- Operator: I-S3 Inc., 638-3 Mine, Annaka, Gunma, Japan. Corporate site: https://www.i-s3.com/
- Disclaimer (all pages): RightOS is a verification infrastructure for places, time slots, queues, and usage rights. It does not arrange vehicles, set fares, assign drivers, or broker dispatch.