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

# Team Collaboration API

> Multi-user team management, member invitations, and role-based access control

## Overview

The Team Collaboration API enables multi-user dealerships to manage teams, invite members, assign roles, and control access permissions. Perfect for organizations with multiple salespeople, managers, and administrators.

## Key Features

<CardGroup cols={2}>
  <Card title="Team Management" icon="users">
    Create and manage multiple teams within your organization
  </Card>

  <Card title="Member Invitations" icon="envelope">
    Invite team members via email with role assignments
  </Card>

  <Card title="Role-Based Access" icon="shield">
    Control what team members can access and modify
  </Card>

  <Card title="Audit Trail" icon="clock">
    Track team activities and membership changes
  </Card>
</CardGroup>

## Endpoints

### List All Teams

<ParamField path="GET" type="endpoint">
  /teams
</ParamField>

Retrieve all teams with optional filtering and sorting.

**Query Parameters:**

<ParamField query="search" type="string">
  Search by team name or slug
</ParamField>

<ParamField query="ownerId" type="string">
  Filter by team owner ID
</ParamField>

<ParamField query="sortBy" type="enum">
  Sort field: `name`, `createdAt` (default: name)
</ParamField>

<ParamField query="sortOrder" type="enum">
  Sort direction: `asc` (default), `desc`
</ParamField>

**Response:**

```json theme={null}
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Downtown Dealership",
    "slug": "downtown-dealership",
    "ownerId": "owner_uuid",
    "createdAt": "2024-01-15T10:30:00Z",
    "owner": {
      "id": "owner_uuid",
      "name": "John Doe",
      "email": "john@dealership.com"
    },
    "memberCount": 12,
    "roleCount": 4,
    "invitationCount": 2
  }
]
```

***

### Get My Teams

<ParamField path="GET" type="endpoint">
  /teams/my
</ParamField>

Retrieve all teams where the current user is a member or owner.

**Response:**

Array of team objects where user has membership.

***

### Get Team by ID

<ParamField path="GET" type="endpoint">
  /teams/{id}
</ParamField>

Retrieve detailed information about a specific team.

**Path Parameters:**

<ParamField path="id" type="string" required>
  Team UUID
</ParamField>

**Query Parameters:**

<ParamField query="includeDetails" type="boolean">
  Include members, roles, and pending invitations (default: false)
</ParamField>

**Response:**

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Downtown Dealership",
  "slug": "downtown-dealership",
  "ownerId": "owner_uuid",
  "createdAt": "2024-01-15T10:30:00Z",
  "owner": {
    "id": "owner_uuid",
    "name": "John Doe",
    "email": "john@dealership.com"
  },
  "members": [
    {
      "id": "member_uuid",
      "name": "Jane Smith",
      "email": "jane@dealership.com",
      "image": "https://...",
      "createdAt": "2024-01-15T10:30:00Z",
      "role": {
        "id": "role_uuid",
        "name": "Sales Manager",
        "permissions": ["view_inventory", "edit_inventory", "view_analytics"]
      },
      "isOwner": false
    }
  ],
  "memberCount": 12,
  "roleCount": 4,
  "invitationCount": 2
}
```

***

### Get Team by Slug

<ParamField path="GET" type="endpoint">
  /teams/slug/{slug}
</ParamField>

Retrieve team information using the team's URL-friendly slug.

**Path Parameters:**

<ParamField path="slug" type="string" required>
  Team slug (e.g., "downtown-dealership")
</ParamField>

***

### Create Team

<ParamField path="POST" type="endpoint">
  /teams
</ParamField>

Create a new team. The authenticated user becomes the team owner.

**Request Body:**

```json theme={null}
{
  "name": "North Branch Dealership",
  "slug": "north-branch"
}
```

<ParamField body="name" type="string" required>
  Team display name (max 100 characters)
</ParamField>

<ParamField body="slug" type="string" required>
  URL-friendly identifier (lowercase, numbers, hyphens only, max 50 characters)
</ParamField>

**Response:**

```json theme={null}
{
  "id": "new_team_uuid",
  "name": "North Branch Dealership",
  "slug": "north-branch",
  "ownerId": "current_user_uuid",
  "createdAt": "2024-01-17T11:00:00Z"
}
```

***

### Update Team

<ParamField path="PATCH" type="endpoint">
  /teams/{id}
</ParamField>

Update team information. Only the team owner can update team details.

**Path Parameters:**

<ParamField path="id" type="string" required>
  Team UUID
</ParamField>

**Request Body:**

```json theme={null}
{
  "name": "North Branch Dealership - Updated",
  "slug": "north-branch-updated"
}
```

***

### Delete Team

<ParamField path="DELETE" type="endpoint">
  /teams/{id}
</ParamField>

Delete a team. Only the owner can delete a team, and it must have no active members (except the owner).

**Path Parameters:**

<ParamField path="id" type="string" required>
  Team UUID
</ParamField>

<Warning>
  Cannot delete teams with active members. Remove all members first, or transfer ownership.
</Warning>

***

### Invite Team Member

<ParamField path="POST" type="endpoint">
  /teams/{teamId}/invite
</ParamField>

Invite a user to join the team with a specific role.

**Path Parameters:**

<ParamField path="teamId" type="string" required>
  Team UUID
</ParamField>

**Request Body:**

```json theme={null}
{
  "email": "newmember@dealership.com",
  "roleId": "role_uuid"
}
```

<ParamField body="email" type="string" required>
  Email address of user to invite
</ParamField>

<ParamField body="roleId" type="string" required>
  Role UUID to assign to the member
</ParamField>

**Response:**

```json theme={null}
{
  "id": "invitation_uuid",
  "teamId": "team_uuid",
  "userId": "invited_user_uuid",
  "email": "newmember@dealership.com",
  "roleId": "role_uuid",
  "token": "invitation_token",
  "expiresAt": "2024-01-24T11:00:00Z",
  "user": {
    "id": "invited_user_uuid",
    "name": "New Member",
    "email": "newmember@dealership.com"
  },
  "role": {
    "id": "role_uuid",
    "name": "Salesperson"
  }
}
```

<Info>
  The invited user will receive an email with an invitation link. The invitation expires after 7 days.
</Info>

***

### Accept Team Invitation

<ParamField path="POST" type="endpoint">
  /teams/accept-invitation
</ParamField>

Accept a team invitation using the token from the invitation email.

**Request Body:**

```json theme={null}
{
  "token": "invitation_token_from_email"
}
```

<ParamField body="token" type="string" required>
  Invitation token
</ParamField>

**Response:**

```json theme={null}
{
  "id": "membership_uuid",
  "teamId": "team_uuid",
  "userId": "user_uuid",
  "roleId": "role_uuid",
  "team": {
    "id": "team_uuid",
    "name": "Downtown Dealership",
    "slug": "downtown-dealership"
  },
  "role": {
    "id": "role_uuid",
    "name": "Salesperson",
    "permissions": ["view_inventory", "create_leads"]
  }
}
```

***

### Get Team Members

<ParamField path="GET" type="endpoint">
  /teams/{teamId}/members
</ParamField>

Retrieve all members of a team with their roles and permissions.

**Path Parameters:**

<ParamField path="teamId" type="string" required>
  Team UUID
</ParamField>

**Response:**

```json theme={null}
[
  {
    "id": "member_uuid",
    "name": "Jane Smith",
    "email": "jane@dealership.com",
    "image": "https://...",
    "createdAt": "2024-01-15T10:30:00Z",
    "role": {
      "id": "role_uuid",
      "name": "Sales Manager",
      "permissions": [
        "view_inventory",
        "edit_inventory",
        "delete_inventory",
        "view_analytics",
        "manage_leads",
        "invite_members"
      ]
    },
    "isOwner": false
  }
]
```

***

### Get Pending Invitations

<ParamField path="GET" type="endpoint">
  /teams/{teamId}/invitations
</ParamField>

Retrieve all pending (not yet accepted) invitations for a team.

**Path Parameters:**

<ParamField path="teamId" type="string" required>
  Team UUID
</ParamField>

**Response:**

```json theme={null}
[
  {
    "id": "invitation_uuid",
    "teamId": "team_uuid",
    "email": "pending@dealership.com",
    "roleId": "role_uuid",
    "expiresAt": "2024-01-24T11:00:00Z",
    "user": {
      "id": "user_uuid",
      "name": "Pending User",
      "email": "pending@dealership.com"
    },
    "role": {
      "id": "role_uuid",
      "name": "Salesperson"
    }
  }
]
```

***

### Remove Team Member

<ParamField path="DELETE" type="endpoint">
  /teams/{teamId}/members/{memberId}
</ParamField>

Remove a member from the team. Requires appropriate permissions.

**Path Parameters:**

<ParamField path="teamId" type="string" required>
  Team UUID
</ParamField>

<ParamField path="memberId" type="string" required>
  User ID of member to remove
</ParamField>

**Response:**

```json theme={null}
{
  "success": true,
  "message": "Member removed from team successfully"
}
```

<Warning>
  Cannot remove the team owner. Transfer ownership first if needed.
</Warning>

***

### Cancel Invitation

<ParamField path="DELETE" type="endpoint">
  /teams/invitations/{invitationId}/cancel
</ParamField>

Cancel a pending team invitation.

**Path Parameters:**

<ParamField path="invitationId" type="string" required>
  Invitation UUID
</ParamField>

**Response:**

```json theme={null}
{
  "success": true,
  "message": "Invitation cancelled successfully"
}
```

***

### Get User's Teams

<ParamField path="GET" type="endpoint">
  /teams/user/{userId}
</ParamField>

Retrieve all teams associated with a specific user.

**Path Parameters:**

<ParamField path="userId" type="string" required>
  User UUID
</ParamField>

***

## Team Roles & Permissions

### Default Roles

| Role            | Permissions                           | Description                                 |
| --------------- | ------------------------------------- | ------------------------------------------- |
| **Owner**       | All permissions                       | Full control over team and all resources    |
| **Admin**       | All except team deletion              | Can manage members, inventory, and settings |
| **Manager**     | View/Edit inventory, Analytics, Leads | Sales manager with reporting access         |
| **Salesperson** | View inventory, Create/Edit leads     | Front-line sales staff                      |
| **Viewer**      | View-only access                      | Read-only access to inventory and reports   |

### Permission System

Common permissions include:

* `view_inventory` - View vehicles and listings
* `edit_inventory` - Modify vehicle information
* `delete_inventory` - Remove vehicles
* `create_leads` - Create new leads
* `manage_leads` - Edit and delete all leads
* `view_analytics` - Access dashboard and reports
* `manage_kpis` - Configure KPI dashboard
* `invite_members` - Invite new team members
* `remove_members` - Remove team members
* `manage_roles` - Create and modify roles
* `manage_team` - Edit team settings

## Use Cases

### Example 1: Create Dealership Team

```bash theme={null}
# Create team
curl -X POST "https://api.steerai.autos/v1/teams" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Prime Auto Group",
    "slug": "prime-auto-group"
  }'
```

### Example 2: Invite Sales Team

```bash theme={null}
# Invite salesperson
curl -X POST "https://api.steerai.autos/v1/teams/{teamId}/invite" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "salesperson@dealership.com",
    "roleId": "salesperson_role_uuid"
  }'
```

### Example 3: Monitor Team Activity

```bash theme={null}
# Get team members
curl -X GET "https://api.steerai.autos/v1/teams/{teamId}/members" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Get pending invitations
curl -X GET "https://api.steerai.autos/v1/teams/{teamId}/invitations" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Error Codes

| Code                       | Status | Description                             |
| -------------------------- | ------ | --------------------------------------- |
| `TEAM_NOT_FOUND`           | 404    | Team ID does not exist                  |
| `SLUG_ALREADY_EXISTS`      | 400    | Team slug is already taken              |
| `NOT_TEAM_OWNER`           | 403    | Only team owner can perform this action |
| `INSUFFICIENT_PERMISSIONS` | 403    | User lacks required permissions         |
| `ALREADY_TEAM_MEMBER`      | 400    | User is already a member                |
| `INVITATION_EXPIRED`       | 400    | Invitation token has expired            |
| `INVITATION_NOT_FOUND`     | 404    | Invitation does not exist               |
| `CANNOT_REMOVE_OWNER`      | 400    | Cannot remove team owner                |
| `TEAM_HAS_MEMBERS`         | 400    | Cannot delete team with active members  |

## Best Practices

<AccordionGroup>
  <Accordion title="Use descriptive team names and slugs">
    Choose clear, professional names. Slugs should be URL-friendly and memorable.
  </Accordion>

  <Accordion title="Implement role-based access control">
    Assign appropriate roles based on job functions. Don't give everyone admin access.
  </Accordion>

  <Accordion title="Regularly review team membership">
    Audit team members quarterly. Remove inactive users and update roles as needed.
  </Accordion>

  <Accordion title="Set invitation expiration reminders">
    Follow up on pending invitations before they expire (7 days).
  </Accordion>

  <Accordion title="Document custom roles">
    If you create custom roles, document their permissions clearly for your team.
  </Accordion>

  <Accordion title="Use team slugs for routing">
    Leverage team slugs in URLs for cleaner, more shareable links.
  </Accordion>
</AccordionGroup>

## Integration Patterns

### Multi-Tenant Architecture

```javascript theme={null}
// Check user's team membership
async function getUserTeams(userId) {
  const response = await fetch(
    `https://api.steerai.autos/v1/teams/user/${userId}`,
    {
      headers: { 'Authorization': `Bearer ${API_KEY}` }
    }
  );
  return response.json();
}

// Filter data by team context
async function getTeamInventory(teamId) {
  const response = await fetch(
    `https://api.steerai.autos/v1/vehicles?teamId=${teamId}`,
    {
      headers: { 'Authorization': `Bearer ${API_KEY}` }
    }
  );
  return response.json();
}
```

### Permission Checking

```javascript theme={null}
function hasPermission(member, permission) {
  return member.role.permissions.includes(permission) || member.isOwner;
}

// Usage
if (hasPermission(currentMember, 'edit_inventory')) {
  // Show edit controls
}
```

## Related Resources

<CardGroup cols={2}>
  <Card title="Authentication API" icon="key" href="/api-reference/auth/authentication">
    User authentication and session management
  </Card>

  <Card title="Roles & Permissions" icon="shield-halved" href="/guides/roles-permissions">
    Detailed permission system guide
  </Card>

  <Card title="Multi-Tenant Setup" icon="building" href="/guides/multi-tenant">
    Best practices for multi-location dealerships
  </Card>

  <Card title="Security Guide" icon="lock" href="/guides/security">
    Security best practices for teams
  </Card>
</CardGroup>