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

# Organizations & Teams

Manage your team with organizations, member roles, invitations, and custom permissions.

## Overview

Organizations are the top-level container for everything in HolyDocs. Every project, deployment, and billing subscription belongs to an organization. Whether you're a solo developer or a large team, your account starts with one organization that you can grow over time.

## Creating an Organization

An organization is created automatically when you sign up. To create additional organizations:

**Open the org switcher**

Click your organization name in the top-left corner of the dashboard sidebar.
  **Click Create Organization**

Select **Create Organization** from the dropdown menu.
  **Set the name and slug**

Choose a display name and URL slug for your organization. The slug is used in API endpoints and cannot be changed later.
  **Choose a plan**

Select a plan for the new organization. Each organization has its own billing subscription.

Each organization is billed separately. Creating a new organization does not share the plan or quota from your existing organization.

## Member Roles

HolyDocs has four built-in roles with increasing levels of access:

| Role | Description | Permissions |
|---|---|---|
| **Editor** | Can edit documentation content | Edit pages, submit for review |
| **Member** | Standard team member | Edit pages, manage deployments, view analytics |
| **Admin** | Organization administrator | All member permissions + manage settings, domains, integrations |
| **Owner** | Organization owner | All admin permissions + manage billing, delete organization, transfer ownership |

### Role Hierarchy

Roles follow a strict hierarchy. Each role inherits all permissions from the roles below it:

```
Owner > Admin > Member > Editor
```

A member can only modify users with a lower role than their own. For example, an Admin can change a Member's role to Editor, but cannot change another Admin's role.

### Permission Matrix

| Action | Editor | Member | Admin | Owner |
|---|---|---|---|---|
| View documentation | Yes | Yes | Yes | Yes |
| Edit pages in editor | Yes | Yes | Yes | Yes |
| Trigger deployments | -- | Yes | Yes | Yes |
| View analytics | -- | Yes | Yes | Yes |
| Manage project settings | -- | -- | Yes | Yes |
| Configure domains | -- | -- | Yes | Yes |
| Manage integrations | -- | -- | Yes | Yes |
| Invite members | -- | -- | Yes | Yes |
| Remove members | -- | -- | Yes | Yes |
| Change member roles | -- | -- | Yes | Yes |
| Manage billing | -- | -- | -- | Yes |
| Delete organization | -- | -- | -- | Yes |
| Transfer ownership | -- | -- | -- | Yes |

## Inviting Members

### Dashboard

**Open Members settings**

Navigate to **Settings > Members** in your organization dashboard.
  **Click Invite Member**

Click the **Invite Member** button.
  **Enter email and role**

Enter the invitee's email address and select their role. The default role is **Member**.
  **Send invitation**

Click **Send Invite**. The invitee receives an email with a link to accept the invitation.

### API

```bash
curl -X POST "https://api.holydocs.com/api/v1/org/invite" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane@company.com",
    "role": "member"
  }'
```

### Invitation Lifecycle

Invitations follow this lifecycle:

| Status | Description |
|---|---|
| **Pending** | Invitation sent, waiting for the invitee to accept |
| **Accepted** | Invitee clicked the link and joined the organization |
| **Expired** | Invitation was not accepted within 7 days |
| **Cancelled** | An admin cancelled the invitation before it was accepted |

Pending invitations are listed on the Members settings page. You can resend the invitation email or cancel it at any time.

## Managing Members

### Changing a Member's Role

Admins and owners can change any member's role (within the hierarchy):

```bash
curl -X PATCH "https://api.holydocs.com/api/v1/org/members/MEMBER_ID/role" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "admin"
  }'
```

You cannot change a member's role to **Owner**. Ownership transfer is a separate action that can only be performed by the current owner.

### Removing a Member

Remove a member from the organization:

#### Dashboard

On the **Members** settings page, click the remove icon next to the member's name and confirm.

#### API

```bash
curl -X DELETE "https://api.holydocs.com/api/v1/org/members/MEMBER_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

When a member is removed:

- They immediately lose access to all projects in the organization
- Their active sessions are invalidated
- The action is recorded in the audit log
- They receive an email notification

### Listing Members

```bash
curl "https://api.holydocs.com/api/v1/org/members" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Response:

```json
{
  "data": [
    {
      "id": "mem_abc123",
      "userId": "usr_xyz",
      "role": "owner",
      "createdAt": 1711929600000,
      "user": {
        "id": "usr_xyz",
        "name": "Jane Smith",
        "email": "jane@company.com",
        "image": "https://avatars.example.com/jane.jpg"
      }
    },
    {
      "id": "mem_def456",
      "userId": "usr_uvw",
      "role": "member",
      "createdAt": 1712016000000,
      "user": {
        "id": "usr_uvw",
        "name": "John Doe",
        "email": "john@company.com",
        "image": null
      }
    }
  ]
}
```

## Managing Invitations

### Listing Pending Invitations

```bash
curl "https://api.holydocs.com/api/v1/org/invitations" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Cancelling an Invitation

```bash
curl -X DELETE "https://api.holydocs.com/api/v1/org/invitations/INVITATION_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Organization Settings

Manage your organization's profile and preferences in **Settings > General**:

| Setting | Description |
|---|---|
| **Name** | Organization display name (visible to all members) |
| **Slug** | URL identifier (set at creation, cannot be changed) |
| **Logo** | Organization logo displayed in the dashboard sidebar |
| **Default role** | Role assigned to new members who accept invitations |

## SSO Integration

On **Business** and **Enterprise** plans, you can connect your identity provider for Single Sign-On. When SSO is enabled:

- Members authenticate through your IdP (Okta, Azure AD, Google Workspace, or custom SAML/OIDC)
- New users are auto-provisioned with the mapped role based on IdP group membership
- You can enforce SSO-only login with an optional grace period for the transition

See [SSO](/sso) for full configuration details.

## Transferring Ownership

Only the current owner can transfer ownership to another member:

**Open Members settings**

Navigate to **Settings > Members**.
  **Find the target member**

Locate the member who should become the new owner.
  **Transfer ownership**

Click the member's options menu and select **Transfer Ownership**. Confirm the action.
  **Confirm via email**

Both the current and new owner receive confirmation emails. The transfer takes effect immediately.

Transferring ownership demotes the current owner to **Admin**. This action cannot be undone without the new owner's cooperation.

## Deleting an Organization

Only the owner can delete an organization. Deletion is permanent and removes:

- All projects and their deployments
- All member associations
- All billing history and subscriptions
- All custom domains and DNS configurations

Organization deletion is irreversible. Export any important data before proceeding. Active subscriptions are cancelled immediately with no refund for the remaining billing period.

## Best Practices

**Use the principle of least privilege**

Assign the minimum role each team member needs. Most contributors should be **Members** or **Editors**. Reserve **Admin** for people who need to manage settings and integrations.
  **Audit membership regularly**

Review your member list periodically and remove people who no longer need access. This is especially important when team members leave the company.
  **Use SSO for larger teams**

Once your team exceeds 10 members, SSO simplifies onboarding and offboarding. Members are automatically provisioned and deprovisioned based on your IdP groups.
  **Keep at least two admins**

Ensure at least two people have Admin access in case the owner is unavailable. This prevents lockout situations.