# RightOS — Full Documentation for AI Agents and Developers

Last updated: 2026-07-13 (RightFlow coordination layer v0.1). Sources: this file, https://rightos.i-s3.com/openapi.json, https://rightos.i-s3.com/rightflow-openapi.json, and pages under https://rightos.i-s3.com/software/rightos and /software/rightflow. 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 proves that a valid right is present — not who the holder is. Everyday receptions (queues, reservations, EV charging, package pickup) become digital QR tickets (**Right Tokens**). The same MAY layer can gate multi-agent and multi-authority systems.

**Core principle: Assignment is not authority.** RightOS answers MAY (rights). RightFlow answers NEXT (coordination / reassignment). Execution systems answer HOW. A RightFlow assignment is coordination state only — re-check RightOS before real action when policy requires. Pair with MCP (tools) and A2A-style messaging (complements, not replacements). Do not collapse layers into one central agent. Visibility ≠ necessity: org-wide list_* is integrator/admin; prefer get_* / scoped filters. Coordination tempo: coarse progress only; telemetry stays in execution systems.

Hosted API scope (v0.1): one organization API key. Cross-organization authority federation is not available yet. Concept examples illustrate design patterns; they are not customer case studies.

The core design principle for tickets: 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).

### Related: RightFlow (coordination layer)

- **RightOS** = What may be done? (rights)
- **RightFlow** = What should happen next? (tasks, assignment, order, swap, dependencies, execution state)
- **Your execution system** = How is it done? (navigation, control, physical/digital action)

Start with the concept guide: https://rightos.i-s3.com/software/rightos/docs/concept — Deep essay: https://rightos.i-s3.com/guides/RIGHTOS_RIGHTFLOW_ESSAY.md — Decision guide: https://rightos.i-s3.com/software/rightos/docs/decision — Full markdown EN/JA/zh-CN/zh-TW under https://rightos.i-s3.com/guides/ — Terminology: https://rightos.i-s3.com/guides/RIGHTOS_RIGHTFLOW_TERMINOLOGY.md

RightFlow uses the same organization API key. OpenAPI: https://rightos.i-s3.com/rightflow-openapi.json — Docs: https://rightos.i-s3.com/software/rightflow/docs — Client: https://rightos.i-s3.com/sdk/rightflow.ts — MCP: `npx -y @i-s3/rightflow-mcp` (separate from `@i-s3/rightos-mcp`; setup https://rightos.i-s3.com/software/rightflow/docs/mcp)

RightFlow does not define money (no price/bid/pay), does not dispatch vehicles, and does not control robots. On proposal accept it only **reads** RightOS tokens as a rights gate; it never calls verify/use/cancel/transfer. Rate limits (approx.): 180 req/min per IP, 120/min per org, 60 writes/min per org; HTTP 429 `rate_limited` with Retry-After.

**Who next is multi-signal**, not a fixed queue position: `POST /api/rightflow/tasks/{taskId}/suggest-candidates` ranks candidates by coarse actor `availability` (available / waiting / unavailable) plus request-scoped soft signals (nearZone, busy — never persisted). The built-in `heuristic.v0` is a swappable reference scorer, not the sole optimizer; external engines may rank outside and only POST proposals. Suggest never creates or accepts proposals.

## 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`, `not_yet_valid` (when enforceTimeWindow and before startTime). Every attempt is logged.
- **Queue reference** (ADR-0024): `GET /api/rightos/locations/{locationId}/queue` (public, no PII) returns activeCount, waitingCount, verifiedCount, estimatedWaitMinutes; `?tokenId=` adds aheadCount and queuePosition. `priorityNumber` = daily issue sequence; `queuePosition` = live queue position at issuance. RightOS does not auto-call or assign staff.
- **Policy queue fields** (ADR-0024): `maxActiveTokens` (issue returns 409 queue_full when full), `enforceTimeWindow`, `requireVerifyBeforeUse` (use returns 409 verify_required from issued). All default to null/false per industry preset; override per location.
- **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).
- **Validity / expiry**: each token has an `endTime` (ISO 8601). At issue time you may set `endTime` explicitly; if omitted, the location policy's `defaultValidityMinutes` applies (industry preset examples: shop/clinic 12h, event 24h, ev_charging 4h, pickup 6h). After `endTime`, verification returns `expired` — no separate cancel step. Override `defaultValidityMinutes` (5–43,200 minutes) via PUT /api/rightos/locations/{locationId}/policy or MCP `set_location_policy`. In the Right Console (https://rightos.i-s3.com/software/rightos/console): edit each location's default validity (1–72 hour dropdown); when issuing, choose location default, set duration (1/4/6/12/24/48/72 hours), or set an end date & time; `token.endTime` is shown after issuance.

## 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"}
   Optional: {"locationId":"loc_...","title":"Queue ticket","endTime":"2026-07-11T20:00:00+09:00"}
   → Response has verificationCode + walletUrl (shown once) and token.endTime. Omit endTime to apply the location policy's defaultValidityMinutes. 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 (with validity modes: location default, set duration 1–72h, or end date & time), adding locations (with a live preview of the policy defaults for your country and location type), editing per-location default validity, 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). Official MCP Registry name (published): io.github.suomimasuda/rightos-mcp — https://registry.modelcontextprotocol.io/v0/servers?search=io.github.suomimasuda/rightos-mcp. Set the RIGHTOS_API_KEY environment variable (rk_live_...) for operator tools; without it, public tools still work. 20 tools: list_plans, get_token, verify_token, transfer_token, holder_cancel_token, get_location_policy, list_policies, get_location_queue (public) + list_locations, list_tokens, 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, getLocationQueue/get_location_queue, getLocationPolicyHistory/get_location_policy_history, registerOrganization/register_organization, listLocations/list_locations, listTokens/list_tokens, 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.5 adds queue reference (getLocationQueue, listTokens) and Policy Phase 3 fields (maxActiveTokens, enforceTimeWindow, requireVerifyBeforeUse, queuePosition, not_yet_valid, queue_full, verify_required). 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}/queue — public queue snapshot (no PII; ?tokenId= for aheadCount)
- GET  /api/rightos/tokens — list tokens for your org (auth; ?locationId&status&since=)
- 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 (omit endTime to apply defaultValidityMinutes; 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: transferable, maxTransfers, defaultValidityMinutes, holderSelfCancel; 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: 500 tokens/month, 1 location (30-day Business-class trial on sign-up: 20,000 tokens + API)
- starter (¥2,980/mo or ¥29,800/yr prepaid): 3,000 tokens/month, 3 locations, API
- business (¥9,800/mo or ¥98,000/yr prepaid): 20,000 tokens/month, 20 locations, API
- pro (¥29,800/mo or ¥298,000/yr prepaid): 200,000 tokens/month, unlimited locations, API
- overage: +10% soft grace then hard stop (no metered overage stack)
- C packages (public): Architecture Intensive ¥3,000,000 (100% on booking); Dedicated Environment ¥12,000,000/year (50% contract + 50% go-live)
- RightFlow included on all plans; **API on Free within Free quotas** (500 tokens/mo); Trial = Business-class for 30 days; higher quotas on Starter+
- 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, FAQ, security, and company

- FAQ (public, FAQPage schema): https://rightos.i-s3.com/software/rightos/faq
- Security (public architecture): https://rightos.i-s3.com/software/rightos/security
- Customer stories (anonymized patterns): https://rightos.i-s3.com/software/rightos/stories
- Product Hunt: https://www.producthunt.com/products/rightos
- English SEO mirror: https://rightos.i-s3.com/en/software/rightos (hreflang; same UI via middleware rewrite)
- 20-language SEO mirrors: /{lang}/software/rightos/... (19 langs + ja canonical)
- 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.