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

# Team Management

> Manage your EngageFabric team. Invite members, assign roles (Owner, Admin, Member), and control access to projects and settings.

Manage your team members and their access levels within EngageFabric. Invite colleagues, assign roles, and control who can view or modify your gamification configurations.

## Team Roles

EngageFabric supports four role levels with different permissions:

| Role       | Description        | Permissions                                |
| ---------- | ------------------ | ------------------------------------------ |
| **Owner**  | Organization owner | Full access, transfer ownership, billing   |
| **Admin**  | Team administrator | Full access except billing and ownership   |
| **Member** | Team member        | Create and manage projects, view analytics |
| **Viewer** | Read-only access   | View projects and analytics only           |

### Permission Matrix

| Action             | Owner | Admin | Member | Viewer |
| ------------------ | ----- | ----- | ------ | ------ |
| View projects      | Yes   | Yes   | Yes    | Yes    |
| View analytics     | Yes   | Yes   | Yes    | Yes    |
| Create projects    | Yes   | Yes   | Yes    | No     |
| Modify projects    | Yes   | Yes   | Yes    | No     |
| Manage players     | Yes   | Yes   | Yes    | No     |
| Invite members     | Yes   | Yes   | No     | No     |
| Remove members     | Yes   | Yes   | No     | No     |
| Manage billing     | Yes   | No    | No     | No     |
| Transfer ownership | Yes   | No    | No     | No     |

## Team Member Limits

Team size is limited by your subscription plan:

| Plan         | Team Members |
| ------------ | ------------ |
| Free         | 2            |
| Starter      | 5            |
| Professional | 15           |
| Enterprise   | Unlimited    |

## Inviting Team Members

<Steps>
  <Step title="Navigate to Settings">
    Go to **Settings > Team** in the admin console.
  </Step>

  <Step title="Click Invite Member">
    Click the **Invite Member** button to open the invitation dialog.
  </Step>

  <Step title="Enter Details">
    Provide the email address and select the role for the new member.
  </Step>

  <Step title="Send Invitation">
    Click **Send Invitation** to email the invite link.
  </Step>
</Steps>

### API: Create Invitation

```bash theme={null}
curl -X POST https://api.engagefabric.com/api/v1/team/invitations \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "colleague@company.com",
    "role": "MEMBER"
  }'
```

**Response:**

```json theme={null}
{
  "id": "inv_abc123",
  "email": "colleague@company.com",
  "role": "MEMBER",
  "status": "PENDING",
  "expiresAt": "2025-01-03T12:00:00.000Z",
  "createdAt": "2025-12-31T12:00:00.000Z"
}
```

<Note>
  Invitations expire after **72 hours**. You can resend or cancel pending invitations from the Settings page.
</Note>

## Managing Invitations

### List Pending Invitations

```bash theme={null}
curl -X GET https://api.engagefabric.com/api/v1/team/invitations \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

### Cancel an Invitation

```bash theme={null}
curl -X DELETE https://api.engagefabric.com/api/v1/team/invitations/inv_abc123 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

### Resend an Invitation

Resending an invitation generates a new token and extends the expiry:

```bash theme={null}
curl -X POST https://api.engagefabric.com/api/v1/team/invitations/inv_abc123/resend \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

## Accepting Invitations

When someone receives an invitation email, they can accept it in two ways:

### 1. Click the Email Link

The invitation email contains a link that:

* Validates the invitation token
* Creates the member account (if new user)
* Links to the existing account (if existing user)
* Redirects to the admin console

### 2. API: Accept Invitation

```bash theme={null}
curl -X POST https://api.engagefabric.com/api/v1/team/invitations/accept \
  -H "Content-Type: application/json" \
  -d '{
    "token": "INVITATION_TOKEN",
    "name": "John Doe"
  }'
```

## Managing Team Members

### List Team Members

```bash theme={null}
curl -X GET https://api.engagefabric.com/api/v1/team/members \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

**Response:**

```json theme={null}
{
  "data": [
    {
      "id": "mem_owner123",
      "name": "Jane Smith",
      "email": "jane@company.com",
      "role": "OWNER",
      "createdAt": "2025-11-01T00:00:00.000Z"
    },
    {
      "id": "mem_admin456",
      "name": "John Doe",
      "email": "john@company.com",
      "role": "ADMIN",
      "createdAt": "2025-12-15T10:30:00.000Z"
    }
  ],
  "total": 2
}
```

### Update Member Role

Change a team member's role (requires Owner or Admin role):

```bash theme={null}
curl -X PATCH https://api.engagefabric.com/api/v1/team/members/mem_admin456 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "MEMBER"
  }'
```

<Warning>
  You cannot change the owner's role or your own role. To transfer ownership, use the ownership transfer feature.
</Warning>

### Remove Team Member

```bash theme={null}
curl -X DELETE https://api.engagefabric.com/api/v1/team/members/mem_admin456 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

<Warning>
  Removing a team member revokes their access immediately. This action cannot be undone - you'll need to send a new invitation if you want to re-add them.
</Warning>

## Best Practices

<CardGroup cols={2}>
  <Card title="Least Privilege" icon="shield-check">
    Assign the minimum role needed for each team member's responsibilities.
  </Card>

  <Card title="Regular Audits" icon="clipboard-check">
    Periodically review team members and remove accounts that are no longer needed.
  </Card>

  <Card title="Limit Admins" icon="user-lock">
    Keep the number of Admin accounts small to reduce security risks.
  </Card>

  <Card title="Use SSO" icon="key">
    For enterprise teams, enable SSO to centralize access management.
  </Card>
</CardGroup>

## API Reference

### Endpoints

| Method | Endpoint                      | Description              |
| ------ | ----------------------------- | ------------------------ |
| GET    | `/v1/team/members`            | List all team members    |
| PATCH  | `/v1/team/members/:id`        | Update member role       |
| DELETE | `/v1/team/members/:id`        | Remove team member       |
| GET    | `/v1/team/invitations`        | List pending invitations |
| POST   | `/v1/team/invitations`        | Create new invitation    |
| DELETE | `/v1/team/invitations/:id`    | Cancel invitation        |
| GET    | `/v1/team/invitations/verify` | Verify invitation token  |
| POST   | `/v1/team/invitations/accept` | Accept invitation        |

### Error Codes

| Code                          | Description                             |
| ----------------------------- | --------------------------------------- |
| `TEAM_MEMBER_LIMIT_EXCEEDED`  | Plan limit reached for team members     |
| `INVITATION_EXPIRED`          | Invitation has expired (72-hour window) |
| `INVITATION_ALREADY_ACCEPTED` | Invitation was already used             |
| `CANNOT_MODIFY_OWNER`         | Cannot change owner's role              |
| `CANNOT_REMOVE_SELF`          | Cannot remove your own account          |

***

## Related

<CardGroup cols={2}>
  <Card title="Single Sign-On" icon="key" href="/guides/enterprise-sso">
    Configure SSO for centralized access management
  </Card>

  <Card title="Billing & Plans" icon="credit-card" href="/guides/billing">
    Upgrade your plan to add more team members
  </Card>
</CardGroup>