> ## Documentation Index
> Fetch the complete documentation index at: https://docs.1club.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Integrate with the 1Club platform to access clubs, classes, content, and transactions.

The 1Club Platform API lets you programmatically access and manage your organization's data - clubs, classes, content, and transactions - from your own websites, integrations, and back-office scripts.

## Base URL

All API requests are made to:

```
https://api.1club.ai
```

## 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.

## Authentication

All requests require a customer API key passed as a Bearer token:

```
Authorization: Bearer 1club_sk_live_...
```

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](https://admin.1club.ai).

1. Sign in to the admin dashboard
2. Open **Settings → API Tokens**
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

<Note>
  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.
</Note>

For the full guide — including scope selection, expiry options, revocation, and security best practices — see the [API Tokens](/settings/api-tokens) page.

### Token scopes

Each token is granted access to specific resources with either **Read** or **Write** permission:

* **Read** — allows fetching data (GET requests)
* **Write** — allows creating and updating data (POST/PUT/PATCH requests)

Grant only the scopes the integration actually needs. The Platform API currently supports these scopes:

* `classes:read` - list and read classes
* `content:read` - list and read published content
* `clubs:read` - look up clubs by slug
* `transactions:read` - list and read billing transactions
* `areas:read` - list areas and read their availability
* `bookings:read` - read a booking by external id
* `bookings:write` - create and cancel bookings

To sync bookings from a partner booking platform, see [Channel integration](/api-reference/channel-integration/overview).

### Revoking a token

If a token is leaked or no longer needed, revoke it from **Settings → API Tokens**. Revocation is immediate — any integration using that token will stop working on its next request.

## Quick start

Fetch the list of clubs:

```bash theme={null}
curl https://api.1club.ai/v1/platform/clubs/my-club-slug \
  -H "Authorization: Bearer 1club_sk_live_..."
```

List recent paid transactions (the last 24 hours by default):

```bash theme={null}
curl "https://api.1club.ai/v1/platform/transactions?paymentStatus=paid" \
  -H "Authorization: Bearer 1club_sk_live_..."
```

Browse class schedules:

```bash theme={null}
curl "https://api.1club.ai/v1/platform/classes?startDate=2026-05-01" \
  -H "Authorization: Bearer 1club_sk_live_..."
```

## Rate limiting

* **100 requests per minute** per organization
* When exceeded, the API returns `429 Too Many Requests` with a `Retry-After` header
* Rate limit headers are included in every response:
  * `X-RateLimit-Limit` — max requests per window
  * `X-RateLimit-Remaining` — requests remaining
  * `X-RateLimit-Reset` — seconds until the window resets

## Errors

| Status | Meaning                                                     |
| ------ | ----------------------------------------------------------- |
| `400`  | Invalid request parameters                                  |
| `401`  | Missing or invalid API key                                  |
| `403`  | Token is missing the required scope for this endpoint       |
| `404`  | Resource not found (or doesn't belong to your organization) |
| `429`  | Rate limit exceeded                                         |
| `500`  | Internal server error                                       |

## 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.

## Need help?

Contact us at [support@1club.ai](mailto:support@1club.ai) for API access questions or integration support.