開発者向けドキュメント

Right Tokenとは

Right Tokenは「特定の場所・時間における順番や利用権」を表すデジタル権利です。氏名・電話番号などの個人情報は含みません。トークンにはtokenIdと、発行時に一度だけ利用者へ渡されるverificationCodeが対応し、サーバーにはそのSHA-256ハッシュ（secretHash）のみが保存されます。

検証者は「誰が来たか」ではなく「有効な権利を持つ人が来たか」だけを確認します。

基本フロー

1. Issue — 事業者がRight Tokenを発行し、walletUrl（QR）を利用者に渡す。
2. Hold — 利用者はRight WalletでQRコードとして保持する。
3. Verify — 施設側がQRを読み取り、verificationCodeをハッシュ照合する。
4. Use — サービス提供後に利用済みへ更新する。
5. Cancel — 不要な権利は取消できる。
6. Transfer — 現保持者だけが権利を譲渡できる。新コード発行と同時に旧コードは無効化される。

認証

事業者向けエンドポイントには、仮登録時に一度だけ発行されるAPIキー（rk_live_...）が必要です。Authorization: Bearer ヘッダーまたは x-rightos-key ヘッダーで送信してください。キーはサーバーに保存されず、ハッシュ照合のみ行われます。

SDK（TypeScript / Python）

公式SDKを提供しています。npm（@i-s3/rightos）とPyPI（rightos-sdk）からインストールできます。どちらも依存ゼロの単一ファイルとしても配布しており、ダウンロードしてそのままプロジェクトに置くだけでも使えます。ソースコードはGitHubで公開しています： github.com/suomimasuda/rightos-sdk

• npm install @i-s3/rightos / rightos.ts — TypeScript (Node.js 18以上・ブラウザ対応、fetchベース)
• pip install rightos-sdk / rightos.py — Python (3.9以上、標準ライブラリのみ)

TypeScript

import { RightOS } from "@i-s3/rightos"; // npm install @i-s3/rightos

const client = new RightOS({ apiKey: "rk_live_..." });
const [location] = await client.listLocations();
const issued = await client.issueToken({
  locationId: location.id,
  title: "Queue ticket",
});
// Hand issued.walletUrl (QR page) to your customer
const outcome = await RightOS.verify(issued.token.id, issued.verificationCode);
// outcome.result === "success"
await client.useToken(issued.token.id);

Python

from rightos import RightOS  # pip install rightos-sdk

client = RightOS(api_key="rk_live_...")
location = client.list_locations()[0]
issued = client.issue_token(location_id=location["id"], title="Queue ticket")
# Hand issued["walletUrl"] (QR page) to your customer
outcome = RightOS().verify_token(issued["token"]["id"], issued["verificationCode"])
# outcome["result"] == "success"
client.use_token(issued["token"]["id"])

MCPサーバー（AIエージェント向け）

MCP対応のAIエージェント（Cursor、Claude Desktop等）からは、公式MCPサーバー（@i-s3/rightos-mcp）で発行・検証・譲渡・ポリシー管理の18ツールが使えます。セットアップはMCPドキュメントをご覧ください。 MCP → · Quickstart →

エラーはRightOSError（status・codeプロパティ付き）として送出されます。policy_transfer_disabled / transfer_limit_reached（409）、rate_limited（429、retryAfterSec付き）などのコードで分岐できます。

ポリシーエンジンと国別ルール

各拠点の有効ポリシー（譲渡可否・最大譲渡回数・既定有効時間・自己キャンセル可否）は、業界プリセット → 国別オーバーレイ（組織の国 × 拠点タイプ） → 拠点上書き の順で解決されます。国別オーバーレイは各国の法令・実運用を踏まえた保守的な既定値で、現在は日本・米国・英国・韓国・台湾・フランス・ドイツ・イタリア・スペイン・オーストラリアの10カ国を収録しています（例: 日本はチケット不正転売禁止法、韓国は2026年改正公演法、フランスは刑法313-6-2条を踏まえ、イベント入場権の譲渡は同伴者への1回のみが既定）。

全定義は認証不要で取得できます（GET /api/rightos/policies）。これは法的助言ではなく推奨既定値であり、拠点上書きでいつでも変更できます。英国のサッカー興行（1994年法166条）のように業種内でも規制が異なる場合は、拠点上書きで transferable: false を設定してください。

Webhooks

token.verified / token.used / token.cancelled / token.transferred の4イベントを、登録したURLへHTTPS POSTで通知します。ペイロードは { id, type, createdAt, data: { token } } のJSONで、秘密値（secretHash等）は含まれません。登録はConsoleまたはAPIから行えます（1組織3件まで）。

すべての配信は x-rightos-signature ヘッダー（t=<unix秒>,v1=<hex>）で署名されます。v1 = HMAC-SHA256(署名シークレット, `${t}.${生のリクエストボディ}`) を受信側で再計算し、一致を確認してください。署名シークレット（whsec_...）は登録時に一度だけ返され、当社サーバーには保存されません。配信はベストエフォート（タイムアウト3秒・再送なし）のため、受信側は即座に2xxを返し、処理は非同期で行ってください。

制限とエラー

レート制限（429）

• verify / transfer: IP+トークンごと10回/分、IP全体で60回/分（検証コードの総当たり対策）。429時はRetry-Afterヘッダーを参照してください。
• 組織登録: IPごと5回/時。

プラン上限（402）

月間発行数（Free 50 / Starter 1,000 / Business 10,000 / Pro 100,000）または拠点数（Free 1 / Starter 3 / Business 20）を超えると402を返します。上位プランへの変更で解消します。

エラーモデル

エラーは JSON（{"error": "<code>"}）で返します。主なコード: missing_api_key / invalid_api_key（401）、プラン上限（402）、demo_org・他組織リソース（403）、not_found（404）、confirmation_required（400）、rate_limited（429）。

エンドポイント

サンプル

発行

POST /api/rightos/tokens/issue
Content-Type: application/json
Authorization: Bearer rk_live_...

{
  "locationId": "loc_shop",
  "title": "順番待ち / Queue ticket",
  "description": "呼び出しまで店外でお待ちください",
  "endTime": "2026-07-08T20:00:00+09:00"
}

201 Created

{
  "token": {
    "id": "tok_2f8a1c9d3e4b5a6f7081",
    "organizationId": "org_demo",
    "locationId": "loc_shop",
    "title": "順番待ち / Queue ticket",
    "priorityNumber": 13,
    "status": "issued",
    "startTime": "2026-07-08T13:30:00.000Z",
    "endTime": "2026-07-08T11:00:00.000Z",
    "createdAt": "2026-07-08T13:30:00.000Z"
  },
  "verificationCode": "K7MP-Q2XT9",
  "walletUrl": "/software/rightos/wallet/tok_2f8a1c9d3e4b5a6f7081?code=K7MP-Q2XT9"
}

検証

POST /api/rightos/tokens/tok_2f8a1c9d3e4b5a6f7081/verify
Content-Type: application/json

{
  "verificationCode": "K7MP-Q2XT9"
}

--> 200 OK
{
  "result": "success",
  "token": { "id": "tok_...", "status": "verified", ... }
}

resultはsuccess / failed / expired / cancelled / already_usedのいずれかです。

セキュリティ設計と将来拡張

• 個人名・電話番号・生年月日を必須にしません。
• 秘密値（verificationCode）はサーバーに保存されず、SHA-256ハッシュのみ保持します。
• QRコードにはtokenIdとverificationCodeのみが含まれます。
• 譲渡はre-keying方式です。譲渡権限は現在のverificationCodeの保持によってのみ証明され、譲渡人・譲受人とも個人情報は不要です。
• 有償譲渡・オークション機能は提供しません（転売・規制リスクのため）。譲渡回数はtransferCountとして記録されます。
• 将来は、利用者端末で生成した鍵ペア（holderPublicKey）へのチャレンジ署名検証（WebCrypto / passkey / wallet signature）に置き換え、コード漏えい耐性を高めます。

RightOSがやらないこと

試してみる

デモトークンで一連の流れを試せます： Right Wallet → Verify