API v1 · OpenID Connect
あなたのサイトを ジムにつなぐ。.
会員がジムのアカウントでログインし、メンバーシップの確認、クラスの予約、スケジュールの表示を自社サイト上で行えます。標準のOpenID Connect、小さなREST API、署名付きWebhookで構成されています。
- OpenID Connect
- PKCE必須
- 署名付きWebhook
01 · クイックスタート
MoveMembers APIクイックスタート: ログイン、交換、読み取り。.
会員はジムのアカウントでログインします。サイトには会員番号を含む署名付きの応答が返るので、どのOIDCライブラリでも使えます。
ボタンを追加する
メンバーを、そのジムのログインページに送ります。PKCEは、機密クライアントか公開クライアントかを問わず、すべてのアプリで必須です。
<!-- "Join Your Gym" -->
<a href="https://movemembers.com/oauth/authorize?client_id=app_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&response_type=code&scope=openid%20member_number%20profile%20email%20phone%20membership%20bookings%20field%3Avisitor_type&redirect_uri=https://yoursite.com/callback&state=…&nonce=…&code_challenge=…&code_challenge_method=S256&prompt=create"
style="display:inline-flex;align-items:center;gap:10px;padding:12px 20px;
border-radius:10px;background:#ffffff;color:#14161b;border:1px solid #e4e6ef;
font-family:inherit;
font-size:15px;font-weight:600;text-decoration:none">
Join Your Gym
</a>サーバー側でコードを交換
ジムが署名したIDトークン(ES256、鍵は/oauth/jwks)を受け取ります。この交換はページ上では絶対に行わないでください。クライアントシークレットが必要です。
const { Issuer } = require("openid-client"); // any certified OIDC client works
const issuer = await Issuer.discover("https://movemembers.com");
const client = new issuer.Client({
client_id: "app_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
client_secret: process.env.APP_SECRET, // never hard-code this
redirect_uris: ["https://yoursite.com/callback"],
response_types: ["code"],
});
// codeVerifier is the one you generated before redirecting the member
const tokenSet = await client.callback(
"https://yoursite.com/callback",
params, // req.query, from the redirect
{ code_verifier: codeVerifier, state, nonce },
);
// tokenSet.claims() is verified against the gym's public keys at /oauth/jwks
const member = tokenSet.claims();クレームを読み取る
ジムが確認し、会員が承認した情報のみです。レコードは「sub」に紐づけ、メールアドレスには紐づけないでください。
{
"sub": "mbr_4Hq9kR2vLpXsT8nZ",
"member_number": "1042",
"name": "Nok Suwan",
"email": "nok@example.com",
"email_verified": true,
"phone_number": "+66812345678",
"membership": { "status": "active", "plan": "Monthly", "ends": "2026-11-01" },
"fields": { "visitor_type": "…" }
}04 · 会員の確認
会員番号と メールアドレスをあわせて確認。.
サーバー間通信で、アプリトークン(client_credentials、scope=lookup)を使います。リクエストの本文に入れて送り、アドレスには含めないでください。アドレスはサーバーログに残ります。
応答は常に200で、「active」という1つの項目だけを返します。フォームを使って誰が会員かを調べることはできません。本文の形式が不正な場合のみ、400 invalid_requestを返します。
レシピ
ジムAPIの 活用レシピ。.
書き込み系のエンドポイントはすべて、ジム自身のアプリとまったく同じルールで動きます。予約受付期間、キャンセル待ち、プランの確認などです。
レコードを紐づける
サイト上のレコードをメンバーに紐づける
犬、ロッカー、車など。自社のレコードに外部キーとして「sub」を保存し、メールアドレスは保存しないでください。状態はあとからアプリトークンで再確認できます。
ガイドを見るクラスを予約
会員に代わって予約・キャンセル
スケジュールを取得し、会員のアクセストークンで予約します。「booking_refused」には必ず会員が理解できる理由が付くので、error.messageを表示してください。
ガイドを見るスケジュールと料金
スケジュールと料金を表示
公開情報のため、メンバーのサインインは不要です。scope=scheduleのアプリトークン1つで、/scheduleと/offersを読み取れます。
ガイドを見る確認してからグループを設定
第三者で本人確認をしてからグループを設定
プロバイダは結果をブラウザのページではなく、あなたのサーバーに送ります。送るのは会員が該当したグループだけで、本人情報は送らないでください。
ガイドを見る05 · Webhook
署名付きWebhookは、 数行で検証できます。.
member.connected、member.disconnected、member.status_changed、booking.created、booking.cancelled、payment.completed、member.group_changed。2xxが返らない場合は、約3時間かけて最大5回再送します。
生の本文で検証し、署名から5分以上たったものは拒否し、X-Webhook-Idで重複を排除してください。署名シークレットは、アプリのWebhookタブに一度だけ表示されます。
10 · リファレンス
MoveMembers APIの全エンドポイント.
すべてJSONです。あなたのサイトからの呼び出しだからといって、動作が変わることはありません。
| 方法 | パス | できること | 認証 |
|---|---|---|---|
| GET | /.well-known/openid-configuration | ディスカバリードキュメント | none |
| GET | /oauth/jwks | 公開署名鍵 | none |
| GET | /oauth/authorize | ログインまたは新規登録を開始 | none |
| POST | /oauth/token | コードの交換、更新、またはアプリトークンの取得 | アプリの認証情報 |
| GET | /oauth/userinfo | ログイン中のメンバーのクレーム | member, Bearer |
| POST | /oauth/revoke | トークンを失効させる | アプリの認証情報 |
| GET | /api/v1/me | ログイン中のメンバー | member, Bearer |
| GET | /api/v1/me/bookings | 予約とプラン(残りクラス数、日付、請求額) | member, Bearer |
| POST | /api/v1/bookings | メンバーに代わってクラスを予約 | member, Bearer |
| DELETE | /api/v1/bookings/{id} | 予約をキャンセル | member, Bearer |
| GET | /api/v1/members/{member_number} | 番号でメンバーを確認 | アプリ、scope=lookup |
| POST | /api/v1/members/verify | メンバー番号とメールアドレスをあわせて確認 | アプリ、scope=lookup |
| GET | /api/v1/schedule | 公開のクラススケジュール | アプリ、scope=schedule |
| GET | /api/v1/offers | 一般販売中のプランと商品 | アプリ、scope=schedule |
| GET | /api/v1/groups | このアプリが設定できるグループ | アプリ、scope=groups |
| PUT | /api/v1/members/{member_number}/group | メンバーのグループを設定(または解除) | アプリ、scope=groups |
メンバーの同意なしで使えるのは、GET /members/{member_number}とPOST /members/verifyだけです。返るのは、メンバーシップが有効かどうかの情報のみです。
12 · レート制限
レート制限は、 1分ごとに集計します。.
上限を超えると、APIはRetry-Afterヘッダー付きで429 rate_limitedを返します。種類ごとに別枠なので、読み取りが多くても予約の枠は減りません。
11 · エラー
エラーはどこでも同じ形式.
/api/v1のエラーはすべて { "error": { "code", "message", "request_id" } } の形式です。/oauthのエンドポイントは標準のOAuth形式のままなので、OAuthライブラリをそのまま使えます。
| コード | 意味 |
|---|---|
| invalid_request | リクエストの形式が不正です。未知の項目や入力ミス、パラメータの不足、本文が大きすぎる場合などです。 |
| invalid_token | Bearerトークンがないか、期限切れか、失効しています。 |
| insufficient_scope | このトークンには、このエンドポイントに必要なスコープがありません。 |
| capability_off | このジムは、お客様のアプリに対してこの機能を有効にしていません。 |
| plan_required | 現在、このジムのプランには連携アプリが含まれていません。何も削除されず、アップグレードするとすぐに元に戻ります。 |
| not_found | そのリソースは存在しません(またはこのジムのものではありません)。 |
| rate_limited | リクエストが多すぎます。Retry-Afterヘッダーの秒数だけ待ってから、再試行してください。 |
| booking_refused | 予約ルールによりこのリクエストは拒否されました。理由はmessageに記載されています。messageがmembership_で始まる場合、予約は作成されていません。 |
| noshow_blocked | booking_refusedメッセージ:メンバーがジムの無断欠席の上限に達したため、現在オンラインで予約できません。エラーにはcount、threshold、windowDaysが含まれます。 |
| age_restricted | booking_refusedメッセージ:メンバーがクラスの最低年齢に達していません。エラーにはageMinが含まれます。 |
| guardian_required | booking_refusedメッセージ:メンバーは未成年で、ジムはプロフィールに保護者の氏名と電話番号を必要としています。 |
| guardian_consent_required | booking_refusedメッセージ:メンバーは未成年で、ジムは保護者の同意を必要としていますが、まだ記録されていません。 |
| payment_required | この予約は先に支払いが必要です。エラーには、会員の支払いページであるpayment_addressが含まれます。 |
| no_consent | そのメンバーは、まだお客様のアプリに接続していません。 |
| group_not_allowed | そのグループは、ジムがお客様のアプリに対して有効にしたものではありません。 |
request_idはX-Request-Idヘッダーでも送られます。お問い合わせの際に伝えていただければ、ログからその呼び出しを特定できます。
質問
MoveMembers APIに関するご質問.
MoveMembers APIは、どのログイン標準を使っていますか?
会員には毎回、同意画面が表示されますか?
レコードはメールアドレスとsubのどちらに紐づけるべきですか?
会員番号とメールアドレスだけで、本人確認になりますか?
クラスに合うプランを会員が持っていない場合はどうなりますか?
使えるWebhookイベントは何ですか?
APIをローカルでテストするには?
ジムの上に、つくる。 まずは自分のアカウントから。.
スタジオを作成し、アプリとlocalhostのリダイレクト先を登録して、一連の流れをテストできます。
- Maxを14日間無料
- クレジットカード不要
- 営業電話なし
続きを読む
関連項目
feature
ジムソフトウェアAPIの概要trust
セキュリティと会員データfeature
クラス予約feature
メンバー管理feature
ジムの自動化pricing
料金demo
ライブデモ、登録不要機能
すべての機能