新機能:ジムの実際の数字で答える AI アシスタント。 詳しく見る

API v1 · OpenID Connect

あなたのサイトを ジムにつなぐ。.

会員がジムのアカウントでログインし、メンバーシップの確認、クラスの予約、スケジュールの表示を自社サイト上で行えます。標準のOpenID Connect、小さなREST API、署名付きWebhookで構成されています。

  • OpenID Connect
  • PKCE必須
  • 署名付きWebhook

API 規約を読む

01 · クイックスタート

MoveMembers APIクイックスタート: ログイン、交換、読み取り。.

会員はジムのアカウントでログインします。サイトには会員番号を含む署名付きの応答が返るので、どのOIDCライブラリでも使えます。

01

ボタンを追加する

メンバーを、そのジムのログインページに送ります。PKCEは、機密クライアントか公開クライアントかを問わず、すべてのアプリで必須です。

認可リクエストHTML
<!-- "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>
02

サーバー側でコードを交換

ジムが署名したIDトークン(ES256、鍵は/oauth/jwks)を受け取ります。この交換はページ上では絶対に行わないでください。クライアントシークレットが必要です。

コード例Node.js
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();
03

クレームを読み取る

ジムが確認し、会員が承認した情報のみです。レコードは「sub」に紐づけ、メールアドレスには紐づけないでください。

IDトークンのクレームJSON
{
  "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を返します。種類ごとに別枠なので、読み取りが多くても予約の枠は減りません。

300読み取り呼び出し数 / アプリ / 分/me、/me/bookings、/schedule、/offers、/groups
120書き込み呼び出し数 / アプリ / 分予約とグループ
120会員確認数 / アプリ / 分lookupとverifyで共有する1つの上限枠
600/api/v1への呼び出し数 / 分同じジムのすべてのアプリで共有

11 · エラー

エラーはどこでも同じ形式.

/api/v1のエラーはすべて { "error": { "code", "message", "request_id" } } の形式です。/oauthのエンドポイントは標準のOAuth形式のままなので、OAuthライブラリをそのまま使えます。

コード意味
invalid_requestリクエストの形式が不正です。未知の項目や入力ミス、パラメータの不足、本文が大きすぎる場合などです。
invalid_tokenBearerトークンがないか、期限切れか、失効しています。
insufficient_scopeこのトークンには、このエンドポイントに必要なスコープがありません。
capability_offこのジムは、お客様のアプリに対してこの機能を有効にしていません。
plan_required現在、このジムのプランには連携アプリが含まれていません。何も削除されず、アップグレードするとすぐに元に戻ります。
not_foundそのリソースは存在しません(またはこのジムのものではありません)。
rate_limitedリクエストが多すぎます。Retry-Afterヘッダーの秒数だけ待ってから、再試行してください。
booking_refused予約ルールによりこのリクエストは拒否されました。理由はmessageに記載されています。messageがmembership_で始まる場合、予約は作成されていません。
noshow_blockedbooking_refusedメッセージ:メンバーがジムの無断欠席の上限に達したため、現在オンラインで予約できません。エラーにはcount、threshold、windowDaysが含まれます。
age_restrictedbooking_refusedメッセージ:メンバーがクラスの最低年齢に達していません。エラーにはageMinが含まれます。
guardian_requiredbooking_refusedメッセージ:メンバーは未成年で、ジムはプロフィールに保護者の氏名と電話番号を必要としています。
guardian_consent_requiredbooking_refusedメッセージ:メンバーは未成年で、ジムは保護者の同意を必要としていますが、まだ記録されていません。
payment_requiredこの予約は先に支払いが必要です。エラーには、会員の支払いページであるpayment_addressが含まれます。
no_consentそのメンバーは、まだお客様のアプリに接続していません。
group_not_allowedそのグループは、ジムがお客様のアプリに対して有効にしたものではありません。

request_idはX-Request-Idヘッダーでも送られます。お問い合わせの際に伝えていただければ、ログからその呼び出しを特定できます。

質問

MoveMembers APIに関するご質問.

MoveMembers APIは、どのログイン標準を使っていますか?
標準のOpenID Connectで、機密クライアントか公開クライアントかを問わず、すべてのアプリでPKCEが必須です。認定済みのOIDCクライアントライブラリであればどれでも使え、ディスカバリードキュメントは/.well-known/openid-configurationにあります。
会員には毎回、同意画面が表示されますか?
いいえ。そのデバイスでジムにサインインしたままであれば、サインイン画面は省略され、承認はメンバーとアプリごとに1回だけ表示されます。本当に必要な場合を除き、prompt=login、prompt=consent、max_ageは使わないでください。
レコードはメールアドレスとsubのどちらに紐づけるべきですか?
「sub」です。この会員とこのアプリの組み合わせでは、メールアドレスを変更しても値は変わりません。「email_verified」がfalseのときは、未確認として扱ってください。
会員番号とメールアドレスだけで、本人確認になりますか?
いいえ。誰かがその情報を知っているという証明にはなりますが、本人である証明にはなりません。アカウントの持ち主だと確かめるには、ログインボタンを使って「sub」を読み取ってください。
クラスに合うプランを会員が持っていない場合はどうなりますか?
予約はmembership_で始まるメッセージ付きのbooking_refusedを返し、予約は作成されません。GET /me/bookingsを読み取り、会員にプランの購入を案内してください。
使えるWebhookイベントは何ですか?
member.connected、member.disconnected、member.status_changed、booking.created、booking.cancelled、payment.completed、member.group_changedを、署名付きのPOSTで送信します。
APIをローカルでテストするには?
http://localhost(ポートは任意)をリダイレクト先として登録してください。これは、通常のhttpで受け付けられる唯一のアドレスです。公開前に、本番のアドレスを追加してください。

ジムの上に、つくる。 まずは自分のアカウントから。.

スタジオを作成し、アプリとlocalhostのリダイレクト先を登録して、一連の流れをテストできます。

  • Maxを14日間無料
  • クレジットカード不要
  • 営業電話なし