外部システム連携（Management API）

外部連携の全体像

連携には2つの方向があります。自社システムからUsakeyを操作する方向と、Usakeyから自社システムへ変化を知らせる方向です。前者にAPIキー、後者にWebhook通知を使います。

自社システム → Usakey

APIキーの使い方

APIキーは、自社システムがUsakeyへ安全に操作を依頼するための認証情報です。管理画面の「APIキー」で作成し、連携先ごとに必要最小限の操作だけを許可します。

顧客ポータルのOIDC接続（サインイン設定）の操作には、sso:read / sso:write が必要です。 以前は customers:read / customers:write で扱えましたが、IdPを差し替えられる権限を顧客台帳の権限から分けました。OIDC接続を扱う既存のAPIキーは、新しい権限を付けるまで SCOPE_REQUIRED（HTTP 403）になります。APIキーの権限は作成後に変えられないため、sso:read / sso:write を付けたキーを作り直して連携先を切り替え、古いキーは取り消してください。

連携先ごとの使い分け

自社システム → Usakey

ライセンスを操作する

ライセンスの発行・更新・停止・再開・取消は、/mgmt/v1/ で始まるAPIで行います。通信仕様やOpenAPI上では、これらをManagement APIと表記します。次は、請求システムで入金を確認したあと、製品・利用ルール・顧客を指定してライセンスを発行する例です。

作成のリクエスト（POST）には、Idempotency-Key ヘッダーを付けてください。次の操作では必須で、付けずに送ると IDEMPOTENCY_KEY_REQUIRED で拒否されます: ライセンスの発行とトライアルの変換、顧客・製品・利用ルール・販売店・顧客組織・組織グループ・グループへの所属・ライセンスユーザー・OIDC接続・ライセンスの割当の作成。Webhook通知先の作成では任意ですが、付けると同じように二重の作成を防げます。変更（PATCH）と削除（DELETE）には不要です。

POST /mgmt/v1/licenses
Authorization: Bearer usk_live_…
Idempotency-Key: 7e2c4d5a-6f44-4b8f-90f4-4ee9b34d66e2
Content-Type: application/json

{
  "product_id": "prod_01K123EXAMPLE",
  "policy_id": "pol_01K123EXAMPLE",
  "customer_id": "cus_01K123EXAMPLE",
  "expires_at": "2027-08-24T00:00:00Z",
  "entitlements": { "export_pdf": true }
}

この操作には「ライセンスを発行・変更する」権限（licenses:write）が必要です。

製品アプリからメール確認付きで試用を始められるようにする設定（試用に使う利用ルールと、24時間の受付上限）は、管理画面の製品の編集のほか、GET／PATCH /mgmt/v1/products/{product_id}/trial-signup（products:read／products:write）でも読み書きできます。確認は管理画面と同じで、利用ルールを選ぶにはトライアルを含む契約プランが必要です。

製品のファイルの暗号化（同梱するファイルを、ライセンスが有効な端末でだけ開けるようにする機能）は、管理画面の製品の詳細のほか、GET／POST /mgmt/v1/products/{product_id}/sealed-files（products:read／products:write）でも状態を読み、有効にできます。POST は本文なしで、何度送っても同じ結果です（Idempotency-Key は使いません）。有効にした後は無効に戻せません。チームプラン以上が必要で、プランに含まれなければ PLAN_ENTITLEMENT_REQUIRED です。有効にするとすぐに current_key が返ります。暗号化用の鍵に一時的につながらないときは 503 SEALED_FILES_KEY_UNAVAILABLE なので、時間をおいて送り直します。current_key.sealing_key は暗号化ツールに渡す1行の公開鍵で、秘密ではありません。ファイル本体はUsakeyに送りません。暗号化しても、ライセンスが有効な端末の管理者は、アプリが開いた後のデータを取り出せます。また暗号化はファイルを作った人を証明しないので、差し替えを防ぎたいファイルはアプリでハッシュを確かめます。

顧客、利用ルール、端末認証、監査ログなど、そのほかの操作と全項目の定義はAPIリファレンスにまとまっています。

自社システム → Usakey

AIアシスタントから操作する（MCP）

Claude Code、CodexなどのAIアシスタントから、このページのAPIを会話で操作できます。MCP（Model Context Protocol）は、AIアシスタントが外部のサービスを呼び出すための共通の仕組みです。UsakeyはMCPサーバー https://usakey.jp/mcp を公開しており、AIアシスタントに追加してブラウザでログインすると、「このライセンスを一時停止して」のような依頼を受けて、AIがAPIを呼び出します。同じ接続で、製品アプリへの組み込み用のスキルも読めます。

導入の流れ

1. AIアシスタントに、MCPサーバー https://usakey.jp/mcp を追加します（指示文をAIに渡すか、下のコマンドを実行します）。
2. ブラウザでUsakeyにログインし、確認画面で契約組織と許可する範囲を選びます。管理操作を許可する場合は、まず動作確認用（test）、必要な範囲だけにしてください。プロダクション用と両方で「日常の運用を許可する」以上を許可するには、許可する人の2段階認証の登録が必要です。
3. AIアシスタントに日本語で依頼します。ログインの状態はAIアシスタントが保持し、自動で更新します。

# Claude Code（追加後、/mcp で usakey を選んで Authenticate）
claude mcp add --transport http --scope user usakey https://usakey.jp/mcp

# Codex（追加するとブラウザが開いてログインが始まります）
codex mcp add usakey --url https://usakey.jp/mcp

AIに頼む場合の指示文と、確認画面の選び方は製品アプリ組み込み（Runtime API）のクイックスタートにあります。接続は、管理画面のAIアシスタントの接続からいつでも取り消せます。

許可する範囲と、使えるAPIの権限

管理操作を許可できるのは、契約組織のオーナーと管理者です。許可すると、その範囲の権限と環境を持つ、接続専用のAPIキーを作ります（キーの値はどこにも表示しません）。許可した人が契約組織を離れたり、管理操作を許可できない役割に変わったりすると、その接続は使えなくなります。確認画面の既定の選択は、アプリの発行元を確かめられ、あなたの役割で管理操作を許可できる場合は「参照だけ許可する」、それ以外は「スキルだけ使う」です。

操作する環境と「両方」

管理操作を許可するときは、確認画面で操作する環境を選びます。

• 動作確認用（テスト環境の製品だけを操作します）
• プロダクション用（顧客へ配布した製品のライセンスが変わります）
• 両方（動作確認用とプロダクション用の製品を操作します）

「両方」の接続は、同じ権限のAPIキーを環境ごとに1つずつ持ちます。管理画面の「APIキー」には、1つの接続のキーが2つ並びます。2段階認証の条件はプロダクション用と同じです。AIのツールを呼ぶたびに、次の順でどちらのキーを使うかを決めます。

1. ツールの引数 environment（test か live）。「両方」の接続でだけ表示する引数で、APIへは送りません。
2. IDで指した対象の環境（ライセンス → 端末認証 → 利用ルール → 製品の順に調べます）。environment と対象の環境が食い違うときは、APIを呼ばずに止め、ENVIRONMENT_REQUIRED とヒントを返します。
3. IDを指定しない一覧（list_products・list_policies・list_licenses・list_runtime_events）は、environment を省略すると両方を順に呼んでまとめ、各項目に environment を付けて返します。この場合は月間回数を2回使います。続きのページは、環境ごとの位置を持つ cursor で取ります。
4. 製品の作成（create_product）は environment が必須です。製品名と製品コードはtestとliveをまたいで一意なので、同じ製品を両方に作るときは名前とコードを分けます。
5. 利用状況の集計（get_usage_report）は environment か product_id が必要です。testとliveの数は合算しません。
6. 環境で分かれていないもの（顧客・ユーザー単位ライセンス・サインイン設定・Webhook通知・監査ログ・プラン・自社Stripe連携）は、プロダクション用のキーで扱います。

管理画面の操作履歴では、実行者に使ったキーの環境が添えられます（例「MCP: Codex / …（プロダクションのキー）」）。環境・許可する範囲・ツールの種類は、あとから管理画面のAIアシスタントの接続の「設定を編集」で変えられます（保存の前に、直近10分以内の本人確認を求めます）。動作確認用から両方へ広げるときは今のキーをそのまま使い、外した環境のキーと権限が変わるキーは作り直して、古いキーを失効させます。

利用状況（get_usage_report）の active_machines は、期間内に認証して解除していない端末の数です。一時停止中・期限切れのライセンスの端末も含むため、いま製品を使える台数ではありません。

プランで選べない項目は、確認画面で薄く表示され、次の理由が添えられます。

• この契約組織のプランではプロダクション用の製品を作れないため、「プロダクション用」と「両方」は選べません（個人プラン以上）。
• この契約組織のプランでは、ユーザー単位ライセンスを使えません（個人プラン以上）。
• この契約組織のプランでは、顧客組織と販売店を使えません（チームプラン以上）。
• この契約組織のプランでは、顧客ポータルのサインイン設定（OIDC）を使えません（チームプラン以上）。

安全に使うために

• 変更系のツールは自動で承認しないでください。特にライセンスの取消（revoke_license）は元に戻せません。各ツールには参照・追加・変更の区別を付けて、AIアシスタントへ伝えています。
• 元に戻せない操作は、対象の確認が一致したときだけ実行します。ライセンスの取消はキーの末尾4文字（confirm_key_last4）、利用ルールの廃止（retire_policy）と顧客のアーカイブ（archive_customer）は名前（confirm_name）です。AIが利用者に確かめた値かどうかを、承認の前に見てください。
• 顧客名、メモ、metadataなど、Usakeyから取得したデータにAIへの指示が紛れ込む可能性があります。変更の承認は人が行い、許可する範囲を必要最小限にしてください。
• スキルに同梱のスクリプト（SDKの取得）をAIが実行するときは、AIアシスタントの確認画面で内容を確かめてから承認してください。

対応している仕様

• MCP 2026-07-28（Streamable HTTP。セッションを持たず、要求ごとに _meta と MCP-Protocol-Version・Mcp-Method・Mcp-Name ヘッダーを送る方式、server/discover）と、2025-03-26〜2025-11-25の initialize を行う方式
• スキル拡張 io.modelcontextprotocol/skills（skills/list・skills/get・resources/directory/read）と、skill:// のリソース
• OAuth 2.1の認可コード（PKCE S256必須）とリフレッシュトークンのローテーション、Protected Resource Metadata（RFC 9728）、認可サーバーメタデータ（RFC 8414）、Client ID Metadata Document、動的クライアント登録（RFC 7591）、resource（RFC 8707）、iss（RFC 9207）

APIキーで使うローカル版（オプション）

公式SDKには、自分のコンピューターで動かすMCPサーバー（usakey-sdk/mcp/）も同梱しています。ブラウザでのログインの代わりにAPIキーを使うので、CIなどブラウザを開けない環境で使えます。オフライン認証ファイルの発行や、ライセンスキーを会話に出さずにファイルへ保存する操作は、このローカル版だけが行えます。スキルは提供しないため、スキルは上のMCPかZIPで導入してください。

導入の流れ

1. Node.js 20.3以上を用意します。MCPサーバーに追加のパッケージは不要です。
2. 公式SDKをダウンロードし、チェックサムを照合して展開します。MCPサーバーは usakey-sdk/mcp/ にあります。
3. 管理画面の「開発・連携」→「APIキー」で、MCP専用のAPIキーを作成します。まずtest環境で、必要な権限だけにしてください。キーは自分だけが読めるファイルに保存します。
4. 接続を確認してから、お使いのAIアシスタントへ登録します。

次はLinux / macOSで、ホームフォルダへ展開する例です。read の行ではAPIキーを貼り付けてEnterを押します（画面と履歴には残りません）。WindowsではPowerShellの Get-FileHash -Algorithm SHA256 でチェックサムを照合してください。

cd ~
curl -fSLO https://usakey.jp/downloads/usakey-sdk.zip
curl -fSLO https://usakey.jp/downloads/usakey-sdk.zip.sha256
sha256sum -c usakey-sdk.zip.sha256    # macOSでは shasum -a 256 -c
unzip -q usakey-sdk.zip

mkdir -p ~/.usakey && chmod 700 ~/.usakey
read -rs USAKEY_KEY
(umask 077 && printf '%s\n' "$USAKEY_KEY" > ~/.usakey/api-key)
unset USAKEY_KEY

USAKEY_API_URL=https://usakey.jp \
USAKEY_MANAGEMENT_API_KEY_FILE=$HOME/.usakey/api-key \
node ~/usakey-sdk/mcp/bin/usakey-mcp.mjs --check

結果: 接続できました。APIキーは有効です と表示されれば準備完了です。終了コードは、APIキーが有効なら0、接続に失敗したら1です。この確認で、Management APIを1回呼び出します。

claude mcp add usakey --scope user \
  -e USAKEY_API_URL=https://usakey.jp \
  -e USAKEY_MANAGEMENT_API_KEY_FILE=$HOME/.usakey/api-key \
  -- node $HOME/usakey-sdk/mcp/bin/usakey-mcp.mjs

{
  "mcpServers": {
    "usakey": {
      "command": "node",
      "args": ["/Users/<ユーザー名>/usakey-sdk/mcp/bin/usakey-mcp.mjs"],
      "env": {
        "USAKEY_API_URL": "https://usakey.jp",
        "USAKEY_MANAGEMENT_API_KEY_FILE": "/Users/<ユーザー名>/.usakey/api-key"
      }
    }
  }
}

codex mcp add usakey \
  --env USAKEY_API_URL=https://usakey.jp \
  --env USAKEY_MANAGEMENT_API_KEY_FILE=$HOME/.usakey/api-key \
  -- node $HOME/usakey-sdk/mcp/bin/usakey-mcp.mjs

APIキーの権限の選び方

ローカル版を安全に使うために

• 変更系のツールは自動で承認しないでください。特にライセンスの取消（revoke_license）は元に戻せません。各ツールには参照・追加・変更の区別を付けて、AIアシスタントへ伝えています。
• 顧客名、メモ、metadataなど、Usakeyから取得したデータにAIへの指示が紛れ込む可能性があります。変更の承認は人が行い、APIキーの権限を必要最小限にしてください。
• MCPサーバーがこのコンピューターのファイルを読むのは、オフライン認証の要求ファイル（.usakeyreq）を指定したときだけです。それ以外の形式のファイルは、送信する前に拒否します。

全ツールの一覧、設定項目、うまくいかないときの確認方法は、SDKに同梱の usakey-sdk/mcp/README.md にあります。

Usakey → 自社システム

Webhook通知

ライセンスの発行・期限切れ・一時停止・再開・取消や、新しい端末の認証を、自社システムへ自動で知らせます。通知を受け取った自社システムは、CRMの更新、担当者への連絡、更新案内などの後続処理を始められます。通常は、定期的にUsakeyへ問い合わせる必要はありません（送信回数の上限は後述）。

通知先には、自社システム（署名付きJSON）のほか、Slack・Microsoft Teams・Google Chat・Chatworkを選べます。チャットへの通知には署名が付かないため、業務処理の起点には自社システムへの通知を使ってください。

設定と受信の手順

1. 管理画面の「開発・連携」→「Webhook通知」で、公開HTTPSの受信URLと、通知する出来事を登録します。あとで通知先を変更・削除したり、署名シークレットを切り替えたりするときは、直近10分以内の本人確認を求めます。
2. 一度だけ表示される署名シークレットを、自社サーバーの安全な保存領域へ保存します。
3. 受信したJSONを解析する前に、受信したままの本文とヘッダーで署名を確認します。
4. X-Usakey-Event-Id を記録して重複処理を防ぎ、すぐにHTTP 2xxを返します。CRMの更新などの後続の処理は、2xxを返したあとに非同期で行います。

Usakeyは、30秒以内に2xxが返らない配信を失敗として再送します。重い処理を終えてから応答すると、時間切れで同じ通知が何度も届きます。

同じ通知が複数回届くことがあります。 接続エラー、HTTP 408・425・429、HTTP 5xxでは最大24時間再送するためです。そのほかのHTTP 4xxは、再送しても直らない応答として扱い、再送しません。

Webhookの送信は、契約プランの月間回数を消費します。 1回送信するごとに1回と数え、再送も1回ずつ数えます。管理画面の「テスト送信」と「もう一度送る」も1回ずつ数えます。月間回数は検証100回・個人2,000回・チーム20,000回・大規模200,000回です（日本時間の毎月1日に数え直します）。月間回数に達すると、その月のそれ以降の通知は送信も再送もされず、管理画面の「操作履歴」に上限に達したことが記録されるだけです。受信側の障害で再送が続くと早く使い切るため、重要な処理は、Management APIの一覧とも1日1回程度照合してください。Webhook配信の追加枠は現在販売していないため、回数を増やすには上位のプランへの変更が必要です。

通知の署名検証

自社システムへの通知には、次のヘッダーが付きます（チャットへの通知には署名のヘッダーは付きません）。

HMAC-SHA256 は、Usakeyと受信側だけが知る共通シークレットから照合値を作る方式です。署名対象は timestamp.event_id.raw_body、結果は v1=<小文字の16進数> です。raw_body は、空白・改行・キー順を含めた「受信した本文そのもの」を指します。JSONを解析して組み立て直す前に検証してください。署名の鍵には、作成時に表示された署名シークレットの文字列をそのまま（UTF-8のバイト列として）使います。Base64URLとして復号しないでください。

X-Usakey-Timestamp が現在時刻から5分を超えてずれた通知は拒否してください（推奨値です。Usakeyの側で受信側の許容幅は決めていません）。署名シークレットの更新中は、切り替え時刻を境に新しいシークレットで署名されます。切り替え時刻の前後は、新旧どちらのシークレットで作った署名も受け付けてください。

検証コードの例

Ruby

require "openssl"

# raw_body: 受信したままの本文（JSONを解析する前の文字列）
# secrets: 署名シークレットの文字列の配列（更新中は新旧の2つ）
def valid_usakey_signature?(raw_body, headers, secrets, now: Time.now.to_i)
  timestamp = headers.fetch("X-Usakey-Timestamp")
  event_id = headers.fetch("X-Usakey-Event-Id")
  signature = headers.fetch("X-Usakey-Signature")
  return false if (now - Integer(timestamp, 10)).abs > 300 # 5分を超えてずれた通知は拒否する

  signed = "#{timestamp}.#{event_id}.".b + raw_body.b
  secrets.any? do |secret|
    expected = "v1=" + OpenSSL::HMAC.hexdigest("SHA256", secret, signed)
    OpenSSL.secure_compare(expected, signature)
  end
end

Node.js

import { createHmac, timingSafeEqual } from "node:crypto";

// rawBody: 受信したままの本文（Buffer）。JSON.parse の前に確かめる
// secrets: 署名シークレットの文字列の配列（更新中は新旧の2つ）
export function isValidUsakeySignature(rawBody, headers, secrets, now = Math.floor(Date.now() / 1000)) {
  const timestamp = headers["x-usakey-timestamp"] ?? "";
  const eventId = headers["x-usakey-event-id"] ?? "";
  const signature = Buffer.from(headers["x-usakey-signature"] ?? "");
  if (!/^\d+$/.test(timestamp) || Math.abs(now - Number(timestamp)) > 300) return false; // 5分を超えてずれた通知は拒否する

  const signed = Buffer.concat([Buffer.from(`${timestamp}.${eventId}.`), rawBody]);
  return secrets.some((secret) => {
    const expected = Buffer.from(`v1=${createHmac("sha256", secret).update(signed).digest("hex")}`);
    return expected.length === signature.length && timingSafeEqual(expected, signature);
  });
}

通知される出来事と本文

画面や業務設計では日本語名を使います。JSONの type と各IDの項目名は、受信プログラムが判定に使う固定値のため、英語のまま送られます。

{
  "id": "evt_01K789EXAMPLE",
  "type": "activation.created",
  "api_version": "2026-08-24",
  "created_at": "2026-08-25T10:30:00.000+09:00",
  "tenant_id": "ten_01K000EXAMPLE",
  "data": {
    "activation_id": "act_01KABCEXAMPLE",
    "license_id": "lic_01K456EXAMPLE",
    "product_id": "prod_01K123EXAMPLE"
  }
}

api_version はWebhook本文の形式の版で、APIの版とは別に管理しています。

*（すべての出来事を通知する）を選ぶと、今後追加される種類も含めてすべて受け取ります。リスク規則で端末の認証を止めたときは activation.risk_blocked、ライセンスを一時停止したときは license.suspended が届きます。

customer_id は、顧客を割り当てずに発行した場合 null になります。今後の項目追加に備え、受信側は知らない項目を無視してください。