新功能:用您健身房真实数据回答问题的 AI 助手。 了解更多
您经营的是什么?Muay ThaiYogaCrossFitPilatesBoxingSwimming已为以下内容设置的课程、会员、价格和用语: Muay Thai用您的项目来试试演示会根据您的业务调整课程、会员、价格和用语。选择您的项目

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)。切勿在网页里执行这一步换取:它需要用到您的 client secret。

代码示例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」,所以没有人能借您的表单查出谁是会员。只有请求体格式错误时才返回 400 invalid_request。

示例做法

健身房 API 实用范例。.

每个写入接口都沿用健身房自家应用的同一套规则:预约时间窗口、候补名单、套餐校验。

关联记录

把您网站上的一条记录关联到某位会员

无论是宠物、储物柜还是车辆,都请把「sub」作为外键存进您自己的记录,不要存邮箱。之后可用应用令牌重新核验状态。

查看指南

预约课程

代会员预约或取消

先列出课表,再用会员的访问令牌预约。「booking_refused」总会附带会员能看懂的原因:直接显示 error.message 即可。

查看指南

课表与价格

展示您的课表和价格

公开信息,无需会员登录。一个 scope=schedule 的应用令牌即可读取 /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 去重。签名密钥只显示一次,位于应用的 Webhooks 标签页。

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 · 速率限制

速率限制, 按分钟计算。.

超出限制时,API 返回 429 rate_limited 并带有 Retry-After 响应头。每类调用各有独立额度,大量读取不会占用您的预约额度。

300每个应用每分钟读取调用数/me, /me/bookings, /schedule, /offers, /groups
120每个应用每分钟写入调用数预约和团体
120每个应用每分钟会员核验数查询与验证共用一份额度
600/api/v1 每分钟调用数由同一家健身房的所有应用共用

11 · 错误

错误格式,处处一致.

每个 /api/v1 错误的格式都是 { "error": { "code", "message", "request_id" } }。/oauth 端点保持标准 OAuth 格式,所以 OAuth 库可以直接使用。

卡号含义
invalid_request请求格式有误:字段未知或拼写错误、缺少参数,或请求体过大。
invalid_token缺少 Bearer 令牌,或令牌已过期或被撤销。
insufficient_scope该令牌不包含此接口所需的权限范围。
capability_off该健身房尚未为您的应用开启此功能。
plan_required该健身房当前的套餐不包含已连接的应用。不会删除任何内容,升级后立即恢复。
与此人尚无会话该资源不存在(或不属于这家健身房)。
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。
会员每次都会看到授权页面吗?
不会。只要会员在该设备上仍登录着健身房账号,就会跳过登录页面,而且每位会员、每个应用只需授权一次。除非确有需要,请避免使用 prompt=login、prompt=consent 和 max_age。
我应该把记录关联到邮箱还是 sub?
请关联到「sub」。对于同一位会员和同一个应用,它永远不变,即使会员更换了邮箱。「email_verified」为 false 时,请视为未验证。
会员编号加邮箱足以证明身份吗?
不够。它只能证明有人知道这些信息,不能证明对方就是会员本人。要确认是账户持有人,请使用登录按钮并读取其「sub」。
会员没有适用某节课的套餐时会怎样?
预约会返回 booking_refused,消息以 membership_ 开头,且不会创建预约。请读取 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 天
  • 无需信用卡
  • 无需销售来电