API リファレンス

外部サービスがメンバーのプラン情報を照会するための Lookup API の仕様です。

ベース URL

text

https://www.memgate.io/api/v1

認証

Lookup API は2種類のキー認証をサポートしています。いずれも X-API-Key ヘッダーに設定してください。

サーバーキー（mgk_）

バックエンドサーバーから利用するキーです。環境変数で安全に管理してください。

http

GET /api/v1/lookup?note_id=yamada_taro&email=yamada@example.com
Host: memgate.io
X-API-Key: mgk_your_server_key_here

セキュリティに関する注意

サーバーキーはサーバーサイドでのみ使用してください
クライアントサイド（ブラウザの JavaScript）にサーバーキーを埋め込まないでください
キーが漏洩した場合は、管理画面から即座に無効化してください

クライアントキー認証

クライアントキー（mck_ プレフィックス）は Chrome 拡張機能やフロントエンドアプリケーションから直接 Lookup API を呼び出すためのキーです。キー作成時に指定した許可オリジンからのリクエストのみ受け付けます。

http

GET /api/v1/lookup?note_id=yamada_taro&email=yamada@example.com
Host: memgate.io
X-API-Key: mck_your_client_key_here
Origin: chrome-extension://your-extension-id

Origin 検証

クライアントキーを使用する場合、リクエストの Origin ヘッダーがキーに設定された許可オリジンと一致する必要があります。不一致の場合は 403 ORIGIN_FORBIDDEN が返されます。

許可オリジンの形式

chrome-extension://EXTENSION_ID - Chrome 拡張機能
https://your-app.com - Web アプリケーション
http://localhost:3000 - ローカル開発環境

セキュリティモデル

クライアントキーは Stripe の Publishable Key と同等のセキュリティモデルです。ブラウザが Origin ヘッダーを強制するため、悪意ある Web サイトが他者のキーを使用することを防止します。返却データ（メンバーシップステータス）は低機密性のため、このモデルで十分なセキュリティが確保されます。

`GET /api/v1/lookup`

noteID とメールアドレスの組み合わせでメンバーのプラン情報を照会します。

クエリパラメータ

パラメータ	型	必須	説明
`note_id`	`string`	Yes	note ユーザーID（note.com/{noteID} の部分）
`email`	`string`	Yes	メンバーのメールアドレス

リクエスト例

bash

curl "https://www.memgate.io/api/v1/lookup?note_id=yamada_taro&email=yamada@example.com" \
  -H "X-API-Key: mgk_your_api_key_here"

レスポンス: メンバーが見つかった場合

HTTP 200 OK

json

{
  "member": {
    "note_id": "yamada_taro",
    "email": "yamada@example.com",
    "plan": "Proプラン",
    "valid_from": "2026-02-01T00:00:00+09:00",
    "valid_until": "2026-03-01T00:00:00+09:00",
    "status": "active"
  }
}

レスポンスフィールド

フィールド	型	説明
`note_id`	`string`	note ユーザーID
`email`	`string`	メンバーのメールアドレス
`plan`	`string`	メンバーシッププラン名（CSV の値がそのまま入ります）
`valid_from`	`string`	プラン有効開始日時（ISO 8601）
`valid_until`	`string`	プラン有効終了日時（ISO 8601）
`status`	`string`	"active"（有効期間内）または "expired"（期限切れ）

status の判定ロジック

active: valid_until が現在時刻より未来
expired: valid_until が現在時刻以前

レスポンス: メンバーが見つからない場合

HTTP 200 OK（エラーではなく正常レスポンスとして返されます）

json

{
  "member": null,
  "status": "not_found"
}

エラーコード

エラー時は以下の形式で返されます:

json

{
  "error": {
    "code": "ERROR_CODE",
    "message": "人間が読めるエラーメッセージ"
  }
}

HTTP Status	エラーコード	説明
400	`VALIDATION_ERROR`	note_id または email が未指定
401	`UNAUTHORIZED`	API キーが無効または未指定
403	`ORIGIN_FORBIDDEN`	クライアントキーの許可オリジンと不一致
429	`RATE_LIMITED`	レートリミット超過（しばらく待って再試行）
500	`INTERNAL_ERROR`	サーバー内部エラー

レートリミット

Lookup API は API キー単位でレートリミットが適用されます。

エンドポイント	制限	単位
`GET /api/v1/lookup`（サーバーキー）	60 リクエスト/分	API キー
`GET /api/v1/lookup`（クライアントキー）	30 リクエスト/分	API キー

レートリミットに達した場合は 429 が返されます。1分間待ってから再試行してください。