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

# Communities & Access Control

Communities are membership groups that gate access to resources and services. Members can receive booking quotas, access control grants, and exclusive booking permissions.

For general conventions, see [JSON-API Conventions](/developers/guides/json-api-conventions). For authentication, see [Authentication](/developers/guides/authentication).

***

## Prerequisites

* Admin API: Bearer token with admin access + `?o={organization_id}`
* Customer API: Authenticated customer account for membership and invite actions

***

## Concepts

| Entity                | Description                                                          |
| --------------------- | -------------------------------------------------------------------- |
| **Community**         | A named group with members, rules, and permissions                   |
| **Community Account** | A membership record linking a customer account to a community        |
| **Community Invite**  | An email invitation to join a community                              |
| **Booking Pass**      | A quota voucher (e.g. "10x Yoga Class") granted to community members |
| **Account Pass**      | A digital wallet pass (Apple/Google Wallet) for physical access      |

### Member Roles

| Role      | Permissions                                  |
| --------- | -------------------------------------------- |
| `member`  | Standard access according to community rules |
| `manager` | Can manage members and settings              |
| `visitor` | Limited/temporary access                     |

### Member Statuses

| Status     | Meaning           |
| ---------- | ----------------- |
| `accepted` | Active member     |
| `pending`  | Awaiting approval |

Memberships can be time-limited via `start_date` and `end_date` fields on the community account.

***

## Creating a Community (Admin)

```http theme={null}
POST /api/v1/communities?o={org_id}

{
  "data": {
    "type": "communities",
    "attributes": {
      "name": "Premium Members",
      "slug": "premium-members",
      "is_private": true,
      "allow_customer_requests": true,
      "auto_join_enabled": false,
      "include_all_services": false
    }
  }
}
```

### Key Attributes

| Attribute                 | Type    | Description                          |
| ------------------------- | ------- | ------------------------------------ |
| `name`                    | string  | Display name                         |
| `slug`                    | string  | URL-friendly identifier              |
| `is_private`              | boolean | Hidden from public listing if `true` |
| `allow_customer_requests` | boolean | Customers can request to join        |
| `auto_join_enabled`       | boolean | Enable automatic membership rules    |
| `include_all_services`    | boolean | Members can access all services      |
| `welcome_text`            | string  | Shown to members on join             |

***

## Inviting Members (Admin)

Send email invitations to join:

```http theme={null}
POST /api/v1/communities/{community_id}/invites?o={org_id}

{
  "emails": ["jane@example.com", "john@example.com"],
  "role": "member",
  "body": "You've been invited to our Premium Members community!",
  "start_date": "2026-04-01",
  "end_date": "2026-12-31",
  "silent": false
}
```

| Field        | Type      | Required | Description                              |
| ------------ | --------- | -------- | ---------------------------------------- |
| `emails`     | string\[] | Yes      | Email addresses to invite                |
| `role`       | string    | No       | Member role (default: `member`)          |
| `body`       | string    | No       | Custom invitation message                |
| `start_date` | string    | No       | Membership start date                    |
| `end_date`   | string    | No       | Membership expiration date               |
| `silent`     | boolean   | No       | `true` to skip sending invitation emails |

If an email matches an existing customer account, the membership is created immediately.

### Resend an Invitation

```http theme={null}
GET /api/v1/community-invites/{invite_id}/resend?o={org_id}
```

***

## Auto-Join Rules

Communities can automatically add members based on:

| Trigger          | Description                                                       |
| ---------------- | ----------------------------------------------------------------- |
| **Booking**      | Customer books a service linked to the community                  |
| **Subscription** | Customer claims a plan subscription associated with the community |
| **Email Domain** | Customer's email domain matches a verified domain ownership       |

Configure via the `auto_join_settings` attribute on the community resource. Use the sync endpoint to apply rules retroactively:

```http theme={null}
GET /api/v1/communities/{community_id}/sync-auto-join?o={org_id}
```

Returns the number of newly added members.

***

## Customer Membership Actions

Community membership actions are documented in the customer API, not the public API.

### Leave a Community

```http theme={null}
GET /api/v1/communities/{community_id}/leave
```

### Accept an Invite

```http theme={null}
POST /api/v1/community-invites/{invite_id}/accept
```

***

## Common Errors

| Error                        | Cause                                    | Solution                               |
| ---------------------------- | ---------------------------------------- | -------------------------------------- |
| `403` — not a member         | Action requires community membership     | Join the community first               |
| `422` — community is private | Cannot join a private community directly | Request an invitation from an admin    |
| `422` — already a member     | Duplicate join attempt                   | Check membership status before joining |