Team Management API Reference

Team management endpoints allow tenant administrators to invite users, manage roles, and remove team members. The platform uses a role-based access control (RBAC) model with four roles: owner, admin, member, and viewer.

Base URL: /api/team

Authentication: All endpoints require authentication (cookie session or Bearer API key).

Role Hierarchy

Role	Permissions
owner	Full access + billing + team management + delete tenant
admin	Create/manage engagements + team members + view costs
member	Create/run engagements + view deliverables
viewer	Read-only access (for client stakeholders with accounts)

List Team Members

GET /api/team

Returns all team members for the authenticated tenant.

Response

{
  "members": [
    {
      "id": "clxyz200usr",
      "email": "founder@example.com",
      "name": "Jane Smith",
      "role": "owner",
      "lastLoginAt": "2025-06-01T08:00:00.000Z",
      "invitedBy": null,
      "createdAt": "2025-01-15T10:00:00.000Z"
    },
    {
      "id": "clxyz201usr",
      "email": "dev@example.com",
      "name": "John Doe",
      "role": "member",
      "lastLoginAt": "2025-05-30T16:45:00.000Z",
      "invitedBy": "clxyz200usr",
      "createdAt": "2025-03-01T12:00:00.000Z"
    },
    {
      "id": "clxyz202usr",
      "email": "client@example.com",
      "name": null,
      "role": "viewer",
      "lastLoginAt": null,
      "invitedBy": "clxyz200usr",
      "createdAt": "2025-06-01T09:00:00.000Z"
    }
  ]
}

Example

curl -X GET https://app.groundtruth.ai/api/team \
  -H "Authorization: Bearer gt_live_abc123..."

Invite Team Member

POST /api/team

Invites a new user to the tenant. Requires admin or higher role. Supabase sends a magic link email to the invitee automatically.

Request Body

Field	Type	Required	Description
`email`	string	Yes	Email address of the person to invite
`name`	string	No	Display name for the new user
`role`	string	No	One of `"admin"`, `"member"`, `"viewer"` (default: `"member"`)

Note: The owner role cannot be assigned via invitation. Each tenant has exactly one owner, set at registration time.

Response

Status: 201 Created

{
  "id": "clxyz203usr",
  "email": "new-member@example.com",
  "name": "Alice Chen",
  "role": "member",
  "lastLoginAt": null,
  "invitedBy": "clxyz200usr",
  "createdAt": "2025-06-01T14:00:00.000Z"
}

Side Effects

Supabase sends a magic link email to the invitee
The invitee can log in and will be automatically associated with the tenant

Example

curl -X POST https://app.groundtruth.ai/api/team \
  -H "Cookie: sb-access-token=..." \
  -H "Content-Type: application/json" \
  -d '{
    "email": "new-member@example.com",
    "name": "Alice Chen",
    "role": "member"
  }'

Errors

Status	Description
400	Invalid email or role
403	Insufficient permissions (must be admin+)
409	Email already exists in the tenant

Update Member Role

PATCH /api/team/:userId

Changes the role of an existing team member. Requires admin or higher role.

Path Parameters

Parameter	Type	Description
`userId`	string	User ID of the team member

Request Body

Field	Type	Required	Description
`role`	string	Yes	New role: `"admin"`, `"member"`, or `"viewer"`

Constraints

You cannot change your own role
You cannot assign a role equal to or higher than your own (admins cannot make other admins)
You cannot change the owner's role

Response

{
  "id": "clxyz201usr",
  "email": "dev@example.com",
  "name": "John Doe",
  "role": "admin",
  "lastLoginAt": "2025-05-30T16:45:00.000Z",
  "invitedBy": "clxyz200usr",
  "createdAt": "2025-03-01T12:00:00.000Z"
}

Example

curl -X PATCH https://app.groundtruth.ai/api/team/clxyz201usr \
  -H "Cookie: sb-access-token=..." \
  -H "Content-Type: application/json" \
  -d '{
    "role": "admin"
  }'

Errors

Status	Description
400	Invalid role or attempting to change own role
403	Insufficient permissions, attempting to assign role >= own, or attempting to modify owner
404	User not found in the tenant

Remove Team Member

DELETE /api/team/:userId

Removes a team member from the tenant. Requires admin or higher role. The owner cannot be removed.

Path Parameters

Parameter	Type	Description
`userId`	string	User ID of the team member to remove

Response

{
  "success": true
}

Example

curl -X DELETE https://app.groundtruth.ai/api/team/clxyz202usr \
  -H "Cookie: sb-access-token=..."

Errors

Status	Description
403	Insufficient permissions or attempting to remove owner
404	User not found in the tenant

Team Management API Reference

On this page