Team Management API

Last Updated: January 5, 2026
Feature: Multi-User Team Support

The Team Management API enables organizations to collaborate on VerifyHuman with multiple users, role-based permissions, and secure invitation workflows.

Table of Contents

• Overview
• Roles & Permissions
• Plan Limits
• API Endpoints
  • GET /api/team/members
  • POST /api/team/invite
  • POST /api/team/invite/accept
  • PATCH /api/team/members/{id}/role
  • DELETE /api/team/members/{id}
  • GET /api/team/invites
  • DELETE /api/team/invites/{id}
• Invitation Workflow
• Dashboard Access
• Error Handling

Overview

Multi-User Team Support allows organizations to:

• Add team members with different permission levels
• Control access through role-based permissions
• Share resources (API keys, verifications, reports) within the team
• Manage billing through designated team members

Key Features:

• Email-based invitation system
• Three role levels (Owner, Admin, Member)
• Secure token-based invite acceptance
• Plan-based team size limits

Roles & Permissions

Role Descriptions

Owner

• Full administrative control
• Only one owner per organization
• Cannot be removed (can transfer ownership)
• Manages billing and subscription

Admin

• Can manage team members (except owner)
• Full access to API keys and reports
• Cannot modify subscription or billing
• Can invite new members

Member

• Standard access to dashboard features
• Can create and manage own API keys
• View-only for billing information
• Cannot invite or manage other members

Plan Limits

Team size is limited by subscription plan:

Note: Pending invitations count toward the team limit.

API Endpoints

All endpoints require session authentication (logged-in user).

GET /api/team/members

List all team members in your organization.

Response (200):

{
  "members": [
    {
      "id": 1,
      "user_id": 123,
      "email": "owner@company.com",
      "name": "John Owner",
      "role": "owner",
      "joined_at": "2025-01-01T00:00:00Z",
      "last_active": "2025-12-31T10:30:00Z"
    },
    {
      "id": 2,
      "user_id": 456,
      "email": "admin@company.com",
      "name": "Jane Admin",
      "role": "admin",
      "joined_at": "2025-06-15T00:00:00Z",
      "last_active": "2025-12-30T15:00:00Z"
    },
    {
      "id": 3,
      "user_id": 789,
      "email": "member@company.com",
      "name": "Bob Member",
      "role": "member",
      "joined_at": "2025-09-01T00:00:00Z",
      "last_active": "2025-12-29T09:00:00Z"
    }
  ],
  "total": 3,
  "limit": 10
}

POST /api/team/invite

Send an invitation to a new team member.

Required Role: Owner or Admin

Request Body:

{
  "email": "newuser@company.com",
  "role": "member"
}

Parameters:

Response (201):

{
  "message": "Invitation sent successfully",
  "invite": {
    "id": 5,
    "email": "newuser@company.com",
    "role": "member",
    "expires_at": "2025-01-14T00:00:00Z",
    "created_at": "2025-01-07T00:00:00Z"
  }
}

Notes:

• Invitations expire after 7 days
• Email notification sent automatically
• Cannot invite existing team members
• Cannot assign "owner" role via invite

POST /api/team/invite/accept

Accept a team invitation using the token from email.

Request Body:

{
  "token": "invite_abc123xyz456..."
}

Response (200):

{
  "message": "Invitation accepted",
  "organization": "Acme Corp",
  "role": "member"
}

Errors:

• 400 - Invalid or expired token
• 409 - Already a member of this organization

PATCH /api/team/members/{id}/role

Change a team member's role.

Required Role: Owner

Request Body:

{
  "role": "admin"
}

Response (200):

{
  "message": "Role updated successfully",
  "member": {
    "id": 3,
    "email": "member@company.com",
    "role": "admin"
  }
}

Restrictions:

• Only owner can change roles
• Cannot change owner's role
• Valid roles: admin, member

DELETE /api/team/members/{id}

Remove a member from the team.

Required Role: Owner or Admin

Response (200):

{
  "message": "Member removed successfully"
}

Restrictions:

• Owner cannot be removed
• Admins cannot remove other admins
• Members cannot remove anyone

GET /api/team/invites

List pending invitations.

Required Role: Owner or Admin

Response (200):

{
  "invites": [
    {
      "id": 5,
      "email": "pending@company.com",
      "role": "member",
      "invited_by": "owner@company.com",
      "created_at": "2025-01-05T00:00:00Z",
      "expires_at": "2025-01-12T00:00:00Z"
    }
  ],
  "total": 1
}

DELETE /api/team/invites/{id}

Cancel a pending invitation.

Required Role: Owner or Admin

Response (200):

{
  "message": "Invitation cancelled"
}

Invitation Workflow

Sending Invitations

1. Owner/Admin initiates - Goes to Team page, enters email and role
2. System validates - Checks team limit and existing membership
3. Email sent - Invitation email with secure token link
4. 7-day expiry - Invitation expires if not accepted

Accepting Invitations

1. Recipient clicks link - Opens invite page
2. Account check:
   • If logged in: Direct acceptance
   • If no account: Creates account first
   • If different account: Must log out and log in with invited email
3. Join team - Added to organization with assigned role
4. Access granted - Immediate access to team resources

Invitation Email Template

Subject: You've been invited to join [Organization] on VerifyHuman

Hi,

[Inviter Name] has invited you to join [Organization] as a [Role] on VerifyHuman.

Click below to accept:
[Accept Invitation Button]

This invitation expires in 7 days.

If you didn't expect this invitation, you can safely ignore this email.

— The VerifyHuman Team

Dashboard Access

Team Page

Access team management at: Dashboard > Team

Features:

• View all team members
• See pending invitations
• Invite new members (Owner/Admin)
• Manage roles (Owner only)
• Remove members (Owner/Admin)

Activity Visibility

Team members share visibility into:

• All API keys (names and scopes, not secrets)
• All verification history
• All reports and analytics
• Credit balance and usage

Private to each member:

• API key secrets (only shown on creation)
• Personal security settings (2FA)
• Individual login history

Error Handling

Validation Errors (400):

{
  "error": "Invalid email format"
}

Permission Denied (403):

{
  "error": "Only owners can change member roles"
}

Team Limit Reached (403):

{
  "error": "Team limit reached. Upgrade your plan for more members.",
  "current": 10,
  "limit": 10
}

Not Found (404):

{
  "error": "Team member not found"
}

Common Errors:

See Also

• Authentication - API key management
• Security (2FA) - Team security settings
• Dashboard Guide - Team page location