Team Collaboration API - Steer Autos Documentation

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

Team Management

Create and manage multiple teams within your organization

Member Invitations

Invite team members via email with role assignments

Role-Based Access

Control what team members can access and modify

Audit Trail

Track team activities and membership changes

Endpoints

List All Teams

GET

endpoint

/teams

Retrieve all teams with optional filtering and sorting. Query Parameters:

string

Search by team name or slug

ownerId

string

Filter by team owner ID

sortBy

enum

Sort field: name, createdAt (default: name)

sortOrder

enum

Sort direction: asc (default), desc

Response:

[
  {
    "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

GET

endpoint

/teams/my

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

GET

endpoint

/teams/

Retrieve detailed information about a specific team. Path Parameters:

string

required

Team UUID

Query Parameters:

includeDetails

boolean

Include members, roles, and pending invitations (default: false)

Response:

{
  "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

GET

endpoint

/teams/slug/

Retrieve team information using the team’s URL-friendly slug. Path Parameters:

slug

string

required

Team slug (e.g., “downtown-dealership”)

Create Team

POST

endpoint

/teams

Create a new team. The authenticated user becomes the team owner. Request Body:

{
  "name": "North Branch Dealership",
  "slug": "north-branch"
}

name

string

required

Team display name (max 100 characters)

slug

string

required

URL-friendly identifier (lowercase, numbers, hyphens only, max 50 characters)

Response:

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

Update Team

PATCH

endpoint

/teams/

Update team information. Only the team owner can update team details. Path Parameters:

string

required

Team UUID

Request Body:

{
  "name": "North Branch Dealership - Updated",
  "slug": "north-branch-updated"
}

Delete Team

DELETE

endpoint

/teams/

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

string

required

Team UUID

Cannot delete teams with active members. Remove all members first, or transfer ownership.

Invite Team Member

POST

endpoint

/teams//invite

Invite a user to join the team with a specific role. Path Parameters:

teamId

string

required

Team UUID

Request Body:

{
  "email": "newmember@dealership.com",
  "roleId": "role_uuid"
}

string

required

Email address of user to invite

roleId

string

required

Role UUID to assign to the member

Response:

{
  "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"
  }
}

The invited user will receive an email with an invitation link. The invitation expires after 7 days.

Accept Team Invitation

POST

endpoint

/teams/accept-invitation

Accept a team invitation using the token from the invitation email. Request Body:

{
  "token": "invitation_token_from_email"
}

token

string

required

Invitation token

Response:

{
  "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

GET

endpoint

/teams//members

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

teamId

string

required

Team UUID

Response:

[
  {
    "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

GET

endpoint

/teams//invitations

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

teamId

string

required

Team UUID

Response:

[
  {
    "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

DELETE

endpoint

/teams//members/

Remove a member from the team. Requires appropriate permissions. Path Parameters:

teamId

string

required

Team UUID

memberId

string

required

User ID of member to remove

Response:

{
  "success": true,
  "message": "Member removed from team successfully"
}

Cannot remove the team owner. Transfer ownership first if needed.

Cancel Invitation

DELETE

endpoint

/teams/invitations//cancel

Cancel a pending team invitation. Path Parameters:

invitationId

string

required

Invitation UUID

Response:

{
  "success": true,
  "message": "Invitation cancelled successfully"
}

Get User’s Teams

GET

endpoint

/teams/user/

Retrieve all teams associated with a specific user. Path Parameters:

userId

string

required

User UUID

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

# 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

# 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

# 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

Use descriptive team names and slugs

Choose clear, professional names. Slugs should be URL-friendly and memorable.

Implement role-based access control

Assign appropriate roles based on job functions. Don’t give everyone admin access.

Regularly review team membership

Audit team members quarterly. Remove inactive users and update roles as needed.

Set invitation expiration reminders

Follow up on pending invitations before they expire (7 days).

Document custom roles

If you create custom roles, document their permissions clearly for your team.

Use team slugs for routing

Leverage team slugs in URLs for cleaner, more shareable links.

Integration Patterns

Multi-Tenant Architecture

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

function hasPermission(member, permission) {
  return member.role.permissions.includes(permission) || member.isOwner;
}

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

Authentication API

User authentication and session management

Roles & Permissions

Detailed permission system guide

Multi-Tenant Setup

Best practices for multi-location dealerships

Security Guide

Security best practices for teams

API Documentation

​Overview

​Key Features

Team Management

Member Invitations

Role-Based Access

Audit Trail

​Endpoints

​List All Teams

​Get My Teams

​Get Team by ID

​Get Team by Slug

​Create Team

​Update Team

​Delete Team

​Invite Team Member

​Accept Team Invitation

​Get Team Members

​Get Pending Invitations

​Remove Team Member

​Cancel Invitation

​Get User’s Teams

​Team Roles & Permissions

​Default Roles

​Permission System

​Use Cases

​Example 1: Create Dealership Team

​Example 2: Invite Sales Team

​Example 3: Monitor Team Activity

​Error Codes

​Best Practices

​Integration Patterns

​Multi-Tenant Architecture

​Permission Checking

​Related Resources

Authentication API

Roles & Permissions

Multi-Tenant Setup

Security Guide

Overview

Key Features

Endpoints

List All Teams

Get My Teams

Get Team by ID

Get Team by Slug

Create Team

Update Team

Delete Team

Invite Team Member

Accept Team Invitation

Get Team Members

Get Pending Invitations

Remove Team Member

Cancel Invitation

Get User’s Teams

Team Roles & Permissions

Default Roles

Permission System

Use Cases

Example 1: Create Dealership Team

Example 2: Invite Sales Team

Example 3: Monitor Team Activity

Error Codes

Best Practices

Integration Patterns

Multi-Tenant Architecture

Permission Checking

Related Resources