10分ではじめるRight API

1. 組織を登録する

APIキー（rk_live_...）はこのレスポンスで一度だけ返されます。必ず安全な場所に保存してください。サーバーにはハッシュしか保存されず、再表示はできません。

curl -X POST https://rightos.i-s3.com/api/rightos/organizations \
  -H 'Content-Type: application/json' \
  -d '{"name":"My Shop","contactEmail":"you@example.com","planId":"free"}'

# --> {"organization":{...}, "apiKey":"rk_live_..."}  <- shown EXACTLY ONCE

2. 拠点を確認する

登録時に最初の拠点が自動作成されています。IDを控えてください。

curl https://rightos.i-s3.com/api/rightos/locations \
  -H 'Authorization: Bearer rk_live_...'

# --> {"locations":[{"id":"loc_...", "name":"My Shop", ...}]}

拠点の追加はConsoleからも行えます。タイプ（店舗・クリニック・EV充電・イベントなど）を選ぶと、あなたの国と業種に適用される既定ルール（譲渡可否・自己キャンセル・有効時間）がその場でプレビューされます。

3. QR整理券を発行する

walletUrl（QRページ）をお客様に渡します。verificationCodeもこのレスポンスで一度だけ返されます。有効期限を指定しない場合は拠点ポリシーの既定値が適用されます。

curl -X POST https://rightos.i-s3.com/api/rightos/tokens/issue \
  -H 'Authorization: Bearer rk_live_...' \
  -H 'Content-Type: application/json' \
  -d '{"locationId":"loc_...","title":"Queue ticket"}'

# --> {"token":{"id":"tok_..."}, "verificationCode":"XXXX-YYYYY",
#      "walletUrl":"/software/rightos/wallet/tok_...?code=XXXX-YYYYY"}

4. 来場時に検証する

検証に認証は不要です。結果は success / failed / expired / cancelled / already_used のいずれかです。

curl -X POST https://rightos.i-s3.com/api/rightos/tokens/tok_.../verify \
  -H 'Content-Type: application/json' \
  -d '{"verificationCode":"XXXX-YYYYY"}'

# --> {"result":"success", "token":{...}}

すべての検証はログに記録され、Consoleの「検証ログ」で確認できます（個人情報は含まれません）。

5. サービス提供後に使用済みにする

curl -X POST https://rightos.i-s3.com/api/rightos/tokens/tok_.../use \
  -H 'Authorization: Bearer rk_live_...'

# --> {"token":{"id":"tok_...", "status":"used", ...}}

SDKで同じことを

公式SDK（依存ゼロ）で同じフローを数行で書けます。

TypeScript

// npm install @i-s3/rightos
import { RightOS } from "@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);
await client.useToken(issued.token.id);

Python

# pip install rightos-sdk
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")
# Hand issued["walletUrl"] (QR page) to your customer
outcome = RightOS().verify_token(issued["token"]["id"], issued["verificationCode"])
client.use_token(issued["token"]["id"])

AIエージェントから使う（MCP）

MCP対応のAIエージェント（Cursor、Claude Desktop等）には、公式MCPサーバーを設定するだけで発行・検証・譲渡の18ツールが使えるようになります。

{
  "mcpServers": {
    "rightos": {
      "command": "npx",
      "args": ["-y", "@i-s3/rightos-mcp"],
      "env": { "RIGHTOS_API_KEY": "rk_live_..." }
    }
  }
}

RIGHTOS_API_KEYなしでも公開ツール（プラン・検証・譲渡・ポリシー参照）は使えます。

次のステップ

• APIリファレンス（全13エンドポイント）
• OpenAPI 3.1仕様 ・ llms-full.txt
• Right Console（ブラウザで発行） ・ Verify画面（カメラでQRスキャン）
• SDK・MCPのソースコード（GitHub）