API v1 · OpenID Connect
Connect your site to your gym.
Let members sign in with their gym account, check a membership, book classes and show your schedule on your own site. Standard OpenID Connect, a small REST API and signed webhooks.
- OpenID Connect
- PKCE required
- Signed webhooks
01 · Quick start
MoveMembers API quick start: sign in, exchange, read.
Members sign in with their gym account. Your site gets a signed answer with their member number, so any OIDC library works.
Add the button
Send the member to their gym's sign-in page. PKCE is required for every app, confidential or public.
<!-- "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>Exchange the code on your server
You get an ID token signed by the gym (ES256, keys at /oauth/jwks). Never do this exchange from a page: it needs your client secret.
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();Read the claims
Only what the gym has checked and the member has approved. Link your record to "sub", never to the email address.
{
"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 · Check a member
Check a member number and an email together.
Server to server, with an app token (client_credentials, scope=lookup). Send them in the body, never in the address: an address ends up in server logs.
The answer is always 200 with one field, "active", so nobody can use your form to find out who is a member. Only a malformed body answers 400 invalid_request.
Recipes
Recipes for the gym API.
Every write endpoint calls the exact same rules as the gym's own apps: booking windows, waitlists, plan checks.
Link a record
Link a record on your site to a member
A dog, a locker, a car: store "sub" on your own record as a foreign key, never the email. Re-check the status later with an app token.
See the guideBook a class
Book or cancel on the member's behalf
List the schedule, then book with their access token. A "booking_refused" always carries a reason the member recognises: show error.message.
See the guideSchedule and prices
Show your schedule and prices
Public information, no member sign-in needed. One app token with scope=schedule reads /schedule and /offers.
See the guideVerify, then set a group
Verify identity with a third party, then set a group
The provider calls your server with the result, never a browser page. Send only the group the member earned, never identity data.
See the guide05 · Webhooks
Signed webhooks, verified in a few lines.
member.connected, member.disconnected, member.status_changed, booking.created, booking.cancelled, payment.completed, member.group_changed. Retried up to 5 times over about 3 hours without a 2xx.
Verify on the RAW body, refuse anything signed more than 5 minutes ago, then deduplicate on X-Webhook-Id. The signing secret is shown once, in the app's Webhooks tab.
10 · Reference
All MoveMembers API endpoints.
JSON everywhere. Nothing behaves differently because it came from your site.
| Method | Path | What it does | Auth |
|---|---|---|---|
| GET | /.well-known/openid-configuration | Discovery document | none |
| GET | /oauth/jwks | Public signing keys | none |
| GET | /oauth/authorize | Start a sign-in or sign-up | none |
| POST | /oauth/token | Exchange a code, refresh, or get an app token | app credentials |
| GET | /oauth/userinfo | The signed-in member's claims | member, Bearer |
| POST | /oauth/revoke | Revoke a token | app credentials |
| GET | /api/v1/me | The signed-in member | member, Bearer |
| GET | /api/v1/me/bookings | Their bookings, and their plans (classes left, dates, amount due) | member, Bearer |
| POST | /api/v1/bookings | Book a class on their behalf | member, Bearer |
| DELETE | /api/v1/bookings/{id} | Cancel a booking | member, Bearer |
| GET | /api/v1/members/{member_number} | Check a member by number | app, scope=lookup |
| POST | /api/v1/members/verify | Check a member number and an email together | app, scope=lookup |
| GET | /api/v1/schedule | Public class schedule | app, scope=schedule |
| GET | /api/v1/offers | Plans and products on public sale | app, scope=schedule |
| GET | /api/v1/groups | Groups this app can set | app, scope=groups |
| PUT | /api/v1/members/{member_number}/group | Set (or clear) a member's group | app, scope=groups |
Only GET /members/{member_number} and POST /members/verify work without the member's consent, and they return nothing beyond whether the membership is active.
12 · Rate limits
Rate limits, counted per minute.
Over a limit, the API answers 429 rate_limited with a Retry-After header. Each class has its own budget, so heavy reading never uses up your bookings.
11 · Errors
Errors, one shape everywhere.
Every /api/v1 error looks like { "error": { "code", "message", "request_id" } }. The /oauth endpoints keep the standard OAuth shape, so OAuth libraries work as they are.
| Code | Meaning |
|---|---|
| invalid_request | The request is malformed: an unknown or mistyped field, a missing parameter, a body that is too large. |
| invalid_token | The bearer token is missing, expired, or revoked. |
| insufficient_scope | The token doesn't carry the scope this endpoint needs. |
| capability_off | The gym hasn't enabled this capability for your app. |
| plan_required | The gym's plan doesn't include connected apps right now. Nothing is deleted; it comes back the moment they upgrade. |
| not_found | That resource doesn't exist (or doesn't belong to this gym). |
| rate_limited | Too many requests. Wait the seconds in the Retry-After header, then retry. |
| booking_refused | The booking rules refused this request; message explains why. A message starting with membership_ means no booking was created. |
| noshow_blocked | A booking_refused message: the member reached the gym's no-show limit and can't book online for now. The error carries count, threshold and windowDays. |
| age_restricted | A booking_refused message: the member is under the class's minimum age. The error carries ageMin. |
| guardian_required | A booking_refused message: the member is a minor and the gym needs a guardian name and phone on file. |
| guardian_consent_required | A booking_refused message: the member is a minor and the gym needs the guardian's consent, not recorded yet. |
| payment_required | This booking needs to be paid first. The error carries payment_address, the member's payment page. |
| no_consent | That member hasn't connected to your app yet. |
| group_not_allowed | That group isn't one the gym enabled for your app. |
request_id is also sent as the X-Request-Id header: quote it when you ask for help, it finds your call in the log.
Questions
Questions about the MoveMembers API.
Which sign-in standard does the MoveMembers API use?
Will members see a consent screen every time?
Should I link my records to the email or to sub?
Is a member number and email enough to prove identity?
What happens when a member has no plan for a class?
Which webhook events are available?
How do I test the API locally?
Build on your gym. Start with your own account.
Create your studio, register an app and a localhost return address, and test the whole flow.
- 14 days of Max free
- No credit card
- No sales call
Keep reading
Related
feature
Gym software API overviewfeature
Class bookingfeature
Member managementfeature
Gym automationpricing
PricingFeature
All features