API v1 · OpenID Connect
Verbinden Sie Ihre Website mit Ihrem Studio.
Lassen Sie Mitglieder sich mit ihrem Studiokonto anmelden, Mitgliedschaften prüfen, Kurse buchen und Ihren Stundenplan auf Ihrer eigenen Website anzeigen. Standard-OpenID-Connect, eine schlanke REST-API und signierte Webhooks.
- OpenID Connect
- PKCE erforderlich
- Signierte Webhooks
01 · Schnellstart
Schnellstart zur MoveMembers API: anmelden, tauschen, lesen.
Mitglieder melden sich mit ihrem Studiokonto an. Ihre Website erhält eine signierte Antwort mit der Mitgliedsnummer, daher funktioniert jede OIDC-Bibliothek.
Button hinzufügen
Leiten Sie das Mitglied zur Anmeldeseite seines Studios weiter. PKCE ist für jede App Pflicht, ob vertraulich oder öffentlich.
<!-- "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>Den Code auf Ihrem Server einlösen
Sie erhalten ein vom Studio signiertes ID-Token (ES256, Schlüssel unter /oauth/jwks). Führen Sie diesen Austausch nie aus einer Seite heraus durch: Er benötigt Ihr 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();Die Claims auslesen
Nur das, was das Studio geprüft und das Mitglied freigegeben hat. Verknüpfen Sie Ihren Datensatz mit "sub", nie mit der E-Mail-Adresse.
{
"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 · Mitglied prüfen
Prüfen Sie Mitgliedsnummer und E-Mail gemeinsam.
Server zu Server, mit einem App-Token (client_credentials, scope=lookup). Senden Sie sie im Body, nie in der Adresse: Eine Adresse landet in Server-Logs.
Die Antwort ist immer 200 mit einem einzigen Feld, "active". So kann niemand mit Ihrem Formular herausfinden, wer Mitglied ist. Nur ein fehlerhafter Body ergibt 400 invalid_request.
Rezepte
Rezepte für die Studio-API.
Jeder Schreibzugriff nutzt exakt dieselben Regeln wie die eigenen Apps des Studios: Buchungsfenster, Wartelisten, Tarifprüfungen.
Datensatz verknüpfen
Einen Datensatz Ihrer Website mit einem Mitglied verknüpfen
Ein Hund, ein Spind, ein Auto: Speichern Sie "sub" in Ihrem eigenen Datensatz als Fremdschlüssel, nie die E-Mail. Prüfen Sie den Status später erneut mit einem App-Token.
Zum HandbuchKurs buchen
Im Namen des Mitglieds buchen oder stornieren
Rufen Sie den Stundenplan ab und buchen Sie dann mit dem Zugriffstoken des Mitglieds. Ein "booking_refused" enthält immer einen Grund, den das Mitglied nachvollziehen kann: Zeigen Sie error.message an.
Zum HandbuchStundenplan und Preise
Stundenplan und Preise anzeigen
Öffentliche Informationen, keine Anmeldung des Mitglieds nötig. Ein App-Token mit scope=schedule liest /schedule und /offers.
Zum HandbuchPrüfen, dann eine Gruppe zuweisen
Die Identität über einen Dritten prüfen, dann eine Gruppe setzen
Der Anbieter ruft Ihren Server mit dem Ergebnis auf, nie eine Browserseite. Senden Sie nur die Gruppe, die das Mitglied erreicht hat, nie Identitätsdaten.
Zum Handbuch05 · Webhooks
Signierte Webhooks, in wenigen Zeilen geprüft.
member.connected, member.disconnected, member.status_changed, booking.created, booking.cancelled, payment.completed, member.group_changed. Ohne 2xx-Antwort bis zu 5 Wiederholungen über etwa 3 Stunden.
Prüfen Sie auf dem RAW-Body, lehnen Sie alles ab, was vor mehr als 5 Minuten signiert wurde, und entdoppeln Sie dann über X-Webhook-Id. Das Signatur-Secret wird einmal angezeigt, im Tab Webhooks der App.
10 · Referenz
Alle API-Endpunkte von MoveMembers.
Überall JSON. Nichts verhält sich anders, nur weil der Aufruf von Ihrer Website kommt.
| Zahlungsart | Pfad | Was sie tut | Authentifizierung |
|---|---|---|---|
| GET | /.well-known/openid-configuration | Discovery-Dokument | none |
| GET | /oauth/jwks | Öffentliche Signaturschlüssel | none |
| GET | /oauth/authorize | Eine Anmeldung oder Registrierung starten | none |
| POST | /oauth/token | Einen Code eintauschen, aktualisieren oder ein App-Token abrufen | App-Zugangsdaten |
| GET | /oauth/userinfo | Die Claims des angemeldeten Mitglieds | member, Bearer |
| POST | /oauth/revoke | Ein Token widerrufen | App-Zugangsdaten |
| GET | /api/v1/me | Das angemeldete Mitglied | member, Bearer |
| GET | /api/v1/me/bookings | Seine Buchungen und seine Tarife (verbleibende Kurse, Daten, offener Betrag) | member, Bearer |
| POST | /api/v1/bookings | Im Namen des Mitglieds einen Kurs buchen | member, Bearer |
| DELETE | /api/v1/bookings/{id} | Eine Buchung stornieren | member, Bearer |
| GET | /api/v1/members/{member_number} | Ein Mitglied anhand der Nummer prüfen | App, scope=lookup |
| POST | /api/v1/members/verify | Mitgliedsnummer und E-Mail gemeinsam prüfen | App, scope=lookup |
| GET | /api/v1/schedule | Öffentlicher Kursplan | App, scope=schedule |
| GET | /api/v1/offers | Öffentlich verkaufte Tarife und Produkte | App, scope=schedule |
| GET | /api/v1/groups | Gruppen, die diese App setzen kann | App, scope=groups |
| PUT | /api/v1/members/{member_number}/group | Die Gruppe eines Mitglieds setzen (oder löschen) | App, scope=groups |
Nur GET /members/{member_number} und POST /members/verify funktionieren ohne Einwilligung des Mitglieds, und sie liefern nur zurück, ob die Mitgliedschaft aktiv ist.
12 · Ratenlimits
Ratenlimits, pro Minute gezählt.
Bei Überschreitung antwortet die API mit 429 rate_limited und einem Retry-After-Header. Jede Klasse hat ihr eigenes Kontingent, sodass intensives Lesen nie Ihre Buchungen aufbraucht.
11 · Fehler
Fehler, überall im selben Format.
Jeder /api/v1-Fehler sieht so aus: { "error": { "code", "message", "request_id" } }. Die /oauth-Endpunkte behalten das Standardformat von OAuth, daher funktionieren OAuth-Bibliotheken unverändert.
| Code | Bedeutung |
|---|---|
| invalid_request | Die Anfrage ist fehlerhaft: ein unbekanntes oder falsch geschriebenes Feld, ein fehlender Parameter, ein zu großer Body. |
| invalid_token | Das Bearer-Token fehlt, ist abgelaufen oder wurde widerrufen. |
| insufficient_scope | Das Token enthält nicht den Scope, den dieser Endpunkt benötigt. |
| capability_off | Das Studio hat diese Funktion für Ihre App nicht aktiviert. |
| plan_required | Der Tarif des Studios enthält derzeit keine verbundenen Apps. Nichts wird gelöscht; sie sind sofort wieder da, sobald es upgradet. |
| keine offene Unterhaltung mit dieser Person | Diese Ressource existiert nicht (oder gehört nicht zu diesem Studio). |
| rate_limited | Zu viele Anfragen. Warten Sie die im Retry-After-Header genannten Sekunden ab und versuchen Sie es dann erneut. |
| booking_refused | Die Buchungsregeln haben diese Anfrage abgelehnt; message nennt den Grund. Beginnt eine Meldung mit membership_, wurde keine Buchung angelegt. |
| noshow_blocked | Eine booking_refused-Meldung: Das Mitglied hat das Limit des Studios für Nichterscheinen erreicht und kann vorerst nicht online buchen. Der Fehler enthält count, threshold und windowDays. |
| age_restricted | Eine booking_refused-Meldung: Das Mitglied hat das Mindestalter des Kurses nicht erreicht. Der Fehler enthält ageMin. |
| guardian_required | Eine booking_refused-Meldung: Das Mitglied ist minderjährig, und das Studio benötigt Name und Telefonnummer einer erziehungsberechtigten Person in der Akte. |
| guardian_consent_required | Eine booking_refused-Meldung: Das Mitglied ist minderjährig, und das Studio benötigt die noch nicht erfasste Einwilligung der erziehungsberechtigten Person. |
| payment_required | Diese Buchung muss zuerst bezahlt werden. Der Fehler enthält payment_address, die Zahlungsseite des Mitglieds. |
| no_consent | Dieses Mitglied hat sich noch nicht mit Ihrer App verbunden. |
| group_not_allowed | Diese Gruppe wurde vom Studio für Ihre App nicht freigegeben. |
request_id wird auch als X-Request-Id-Header gesendet: Nennen Sie ihn bei Supportanfragen, damit finden wir Ihren Aufruf im Log.
Fragen
Fragen zur MoveMembers-API.
Welchen Anmeldestandard nutzt die MoveMembers API?
Sehen Mitglieder jedes Mal einen Zustimmungsbildschirm?
Soll ich meine Datensätze mit der E-Mail oder mit sub verknüpfen?
Reichen Mitgliedsnummer und E-Mail als Identitätsnachweis?
Was passiert, wenn ein Mitglied keinen passenden Tarif für einen Kurs hat?
Welche Webhook-Ereignisse gibt es?
Wie teste ich die API lokal?
Bauen Sie auf Ihrem Studio auf. Starten Sie mit Ihrem eigenen Konto.
Legen Sie Ihr Studio an, registrieren Sie eine App und eine localhost-Rücksprungadresse und testen Sie den gesamten Ablauf.
- 14 Tage Max kostenlos
- Ohne Kreditkarte
- Kein Verkaufsgespräch
Weiterlesen
Dazu passend
feature
Kursbuchungfeature
Mitgliederverwaltungfeature
Studio-Automatisierungpricing
PreiseKriterium
Alle Funktionen