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

Read the API Terms

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.

01

Add the button

Send the member to their gym's sign-in page. PKCE is required for every app, confidential or public.

Authorize requestHTML
<!-- "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

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.

Code exampleNode.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

Read the claims

Only what the gym has checked and the member has approved. Link your record to "sub", never to the email address.

ID token claimsJSON
{
  "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 guide

Book 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 guide

Schedule 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 guide

Verify, 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 guide

05 · 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.

MethodPathWhat it doesAuth
GET/.well-known/openid-configurationDiscovery documentnone
GET/oauth/jwksPublic signing keysnone
GET/oauth/authorizeStart a sign-in or sign-upnone
POST/oauth/tokenExchange a code, refresh, or get an app tokenapp credentials
GET/oauth/userinfoThe signed-in member's claimsmember, Bearer
POST/oauth/revokeRevoke a tokenapp credentials
GET/api/v1/meThe signed-in membermember, Bearer
GET/api/v1/me/bookingsTheir bookings, and their plans (classes left, dates, amount due)member, Bearer
POST/api/v1/bookingsBook a class on their behalfmember, Bearer
DELETE/api/v1/bookings/{id}Cancel a bookingmember, Bearer
GET/api/v1/members/{member_number}Check a member by numberapp, scope=lookup
POST/api/v1/members/verifyCheck a member number and an email togetherapp, scope=lookup
GET/api/v1/schedulePublic class scheduleapp, scope=schedule
GET/api/v1/offersPlans and products on public saleapp, scope=schedule
GET/api/v1/groupsGroups this app can setapp, scope=groups
PUT/api/v1/members/{member_number}/groupSet (or clear) a member's groupapp, 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.

300read calls per app / min/me, /me/bookings, /schedule, /offers, /groups
120write calls per app / minbookings and groups
120member checks per app / minone shared budget for lookup and verify
600calls a minute on /api/v1shared by all the apps of one gym

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.

CodeMeaning
invalid_requestThe request is malformed: an unknown or mistyped field, a missing parameter, a body that is too large.
invalid_tokenThe bearer token is missing, expired, or revoked.
insufficient_scopeThe token doesn't carry the scope this endpoint needs.
capability_offThe gym hasn't enabled this capability for your app.
plan_requiredThe gym's plan doesn't include connected apps right now. Nothing is deleted; it comes back the moment they upgrade.
not_foundThat resource doesn't exist (or doesn't belong to this gym).
rate_limitedToo many requests. Wait the seconds in the Retry-After header, then retry.
booking_refusedThe booking rules refused this request; message explains why. A message starting with membership_ means no booking was created.
noshow_blockedA 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_restrictedA booking_refused message: the member is under the class's minimum age. The error carries ageMin.
guardian_requiredA booking_refused message: the member is a minor and the gym needs a guardian name and phone on file.
guardian_consent_requiredA booking_refused message: the member is a minor and the gym needs the guardian's consent, not recorded yet.
payment_requiredThis booking needs to be paid first. The error carries payment_address, the member's payment page.
no_consentThat member hasn't connected to your app yet.
group_not_allowedThat 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?
Standard OpenID Connect with PKCE, required for every app, confidential or public. Any certified OIDC client library works, and the discovery document is at /.well-known/openid-configuration.
Will members see a consent screen every time?
No. The sign-in screen is skipped while they are still signed in to the gym on that device, and approval is shown once per member and app. Avoid prompt=login, prompt=consent and max_age unless you really need them.
Should I link my records to the email or to sub?
To "sub". It never changes for this member and this app, even if they change their email. Treat "email_verified": false as unverified.
Is a member number and email enough to prove identity?
No. It proves someone knows them, not that they are the member. To be sure it is the account holder, use the sign-in button and read their "sub".
What happens when a member has no plan for a class?
The booking answers booking_refused with a message starting with membership_, and no booking is created. Read GET /me/bookings and send the member to buy a plan.
Which webhook events are available?
member.connected, member.disconnected, member.status_changed, booking.created, booking.cancelled, payment.completed and member.group_changed, delivered as signed POSTs.
How do I test the API locally?
Register http://localhost (any port) as a return address: it's the one address accepted over plain http. Add your real production address before going live.

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