Skip to main content
The 1Club Platform API lets you programmatically access and manage your organization’s data - clubs, classes, bookings, contacts, memberships, content, transactions, and more - from your own websites, integrations, and back-office scripts.

​
Base URL

All API requests are made to:

​
Machine-readable resources

Tools and AI agents can read the API and its companion services directly:

​
Official API contract

This documentation is the official source of truth for the 1Club Platform API. If an integration relies on undocumented endpoints, fields, response shapes, or internal behavior outside this spec, we can’t guarantee backward compatibility. Build against what’s documented here to stay stable as the platform evolves. See Versioning and deprecation for how changes and deprecations ship.

​
Authentication

All requests require a customer API key passed as a Bearer token:
The key is tied to your organization, and all responses are scoped to your organization’s data.

​
Creating an API token

API tokens are created from the admin dashboard at admin.1club.ai.
  1. Sign in to the admin dashboard
  2. Open Settings > Organization > APIs & webhooks
  3. Click Create Token
  4. Fill in the token details:
    • Name - a label to identify where this token is used (e.g. “Website Integration”)
    • Description - optional note on what the token is used for
    • Scopes - pick the resources the token can access, and whether each is Read or Write
    • Expires - set an expiry date, or leave empty for a token that never expires
  5. Click Save
  6. Copy the token immediately - it is shown only once and cannot be retrieved later
Creating and revoking API tokens requires the settings.manage.organization permission. Admins and users with full settings management can access this page; managers and other roles cannot.
For the full guide - including scope selection, expiry options, revocation, and security best practices - see the API Tokens page.

​
Token scopes

Each token is granted access to specific resources. Most resources offer Read and Write, and a few add a separate action for an operation that is more than a write:
  • Read - allows fetching data (GET requests)
  • Write - allows creating and updating data (POST/PUT/PATCH requests, and the deletes a resource allows)
  • Delete - contacts:delete and media:delete only, for archiving a contact and permanently deleting a media file
  • Publish - website:publish only, for making website edits public
A token can instead hold the single wildcard scope *, which grants every scope, including ones added later. Scopes carry no hierarchy: products:write does not include products:read, so grant both when an integration reads before it writes. Grant only the scopes the integration actually needs. The Platform API supports these scopes: transactions:write records a settlement (revenue collected outside 1Club, reported as one sum for a gym) and refunds of it. Nothing is charged to anyone. GET /v1/platform/me needs no scope and returns the scopes a key holds - see Verify a key.
A transaction in this API is the record the 1Club admin and member apps call a Charge: what a payer owes for one thing, such as a booking, a membership period, or a product. /v1/platform/transactions returns the same records staff see under Sales > Finance > Charges. See Charges.
To sync bookings from a partner booking platform, see Channel integration.

​
Revoking a token

If a token is leaked or no longer needed, revoke it from Settings > Organization > APIs & webhooks. Revocation is immediate - any integration using that token will stop working on its next request.

​
Quick start

Fetch the list of clubs:
List recent paid transactions (the last 24 hours by default):
Browse class schedules:

​
Rate limiting

  • 100 requests per minute per organization, across every Platform API endpoint
  • Some endpoints have a tighter limit on top, in a separate bucket:
    • Booking writes (create, update, cancel, and adding or removing players): 60 per minute
    • Booking a customer into a class: 60 per minute
    • Reports: 20 per minute
  • When exceeded, the API returns 429 Too Many Requests with a Retry-After header (seconds)
  • Rate limit headers are included in every response:
    • RateLimit-Limit - max requests per window
    • RateLimit-Remaining - requests remaining
    • RateLimit-Reset - seconds until the window resets
    • RateLimit-Policy - the limit and window, for example 100;w=60

​
Errors

Most errors return a JSON body of the shape { "error": "...", "message": "...", "code": "...", "details": { ... } }, where code is a stable, machine-readable reason and details carries structured values when the error has them. Authentication, scope, and rate-limit errors return a shorter body:
  • A missing scope returns { "error": "Insufficient access scope", "requiredScope": "bookings:write" }.
  • An organization on the free plan or in trial returns 403 with code: "PLAN_FEATURE_LOCKED", and an organization that is no longer active returns 403 with code: "ORGANIZATION_NOT_ACTIVE".

​
Security best practices

  • Never commit tokens to source control. Store them in environment variables or a secrets manager.
  • Use the minimum required scopes. Don’t grant write access if only read is needed.
  • Set an expiry on tokens used for short-term scripts or testing.
  • Rotate tokens regularly and revoke any that are no longer in use.
  • Never share tokens in emails, chat messages, or public channels.

​
Using this API from an AI assistant

The same Platform API is exposed over the Model Context Protocol at https://mcp.1club.ai/admin. The normal way to connect a remote MCP client is 1Club OAuth: you sign in on 1Club’s authorization page and nothing is pasted into the assistant. An API key created above is still accepted on the same endpoint when the client sends it as Authorization: Bearer 1club_sk_live_..., which is how developer-managed clients that cannot complete an interactive sign-in connect. The MCP tools are thin wrappers over these endpoints, with the same scopes, rate limits, and error shapes. See Connect an assistant. See the MCP overview for the two servers 1Club runs, and Connect an assistant for setup.

​
Need help?

Contact us at support@1club.ai for API access questions or integration support.