Teams API Documentation

Complete API reference for team management, membership, and multi-tenant applications

Team Operations
Membership
Invitations
User Teams

Overview

The Teams API enables multi-tenant application development with role-based access control. Perfect for organizations, workspaces, and collaborative environments.

Base URL:
https://hub.regardingwork.com/api
Authentication:
JWT Bearer tokens (admin actions only)
Team Roles:
admin (full control) • member (team access)
Multi-Tenant:
Users can belong to multiple teams
Perfect for Multi-Tenant Applications
🏢 Organizations:
Company workspaces with departments
💰 Finance Apps:
Family budgets + business accounts
📊 Project Tools:
Team collaboration platforms

Team Operations

List All Teams

GET /api/teams

Purpose: Get all active teams (public endpoint for discovery)

Authentication: Not required

Response Format:
{
  "teams": [
    {
      "id": 1,
      "name": "Demo Team",
      "slug": "demo-team",
      "description": "A demo team for testing",
      "member_count": 3,
      "requires_approval": true,
      "is_active": true,
      "created_at": "2025-09-03T03:09:07.299881",
      "updated_at": "2025-09-03T03:09:07.299885"
    }
  ]
}

Create Team

POST /api/teams SUPERADMIN ONLY

Purpose: Create a new team (superadmin only)

Headers: Authorization: Bearer {token}

Required Role: SUPERADMIN

Request Body:
{
  "name": "Team Name",
  "slug": "team-slug",
  "description": "Team description",
  "requires_approval": true
}
Response Format:
{
  "message": "Team created successfully",
  "team": {
    "id": 1,
    "name": "Team Name",
    "slug": "team-slug",
    "description": "Team description",
    "member_count": 1,
    "members": [...],
    "requires_approval": true,
    "is_active": true,
    "created_by": 3,
    "created_at": "2025-09-03T03:09:07.299881",
    "updated_at": "2025-09-03T03:09:07.299885"
  }
}

Get Team Details

GET /api/teams/{slug}

Purpose: Get detailed team information including members

Authentication: Not required

Response Format:
{
  "id": 1,
  "name": "Demo Team",
  "slug": "demo-team",
  "description": "A demo team for testing",
  "member_count": 3,
  "members": [
    {
      "id": 1,
      "user_id": 3,
      "role": "admin",
      "status": "active",
      "joined_at": "2025-09-03T03:09:07.324134",
      "user": {
        "id": 3,
        "username": "michelini",
        "profile_photo_url": "/static/uploads/profile_photos/29_ceabe8ae.jpg",
        "bio": null,
        "website_url": null
      }
    }
  ],
  "requires_approval": true,
  "is_active": true,
  "created_by": 3,
  "created_at": "2025-09-03T03:09:07.299881",
  "updated_at": "2025-09-03T03:09:07.299885"
}

Team Membership Management

List Team Members

GET /api/teams/{slug}/members

Purpose: Get all members of a specific team

Authentication: Not required

Add Team Member

POST /api/teams/{slug}/members ADMIN REQUIRED

Purpose: Add a user to the team

Headers: Authorization: Bearer {token}

Required Role: Team admin or SUPERADMIN

Request Body:
{
  "username": "newmember",
  "role": "member"
}

Update Member Role

PUT /api/teams/{slug}/members/{username} ADMIN REQUIRED

Purpose: Update a team member's role

Headers: Authorization: Bearer {token}

Required Role: Team admin or SUPERADMIN

Request Body:
{
  "role": "admin"
}

Remove Team Member

DELETE /api/teams/{slug}/members/{username} ADMIN REQUIRED

Purpose: Remove a member from the team

Headers: Authorization: Bearer {token}

Required Role: Team admin or SUPERADMIN

Team Invitations

Send Team Invitation

POST /api/teams/{slug}/invite ADMIN REQUIRED

Purpose: Invite a user to join the team

Headers: Authorization: Bearer {token}

Required Role: Team admin or SUPERADMIN

Request Body:
{
  "email": "user@example.com",
  "role": "member", 
  "message": "Join our team!"
}
Response Format:
{
  "message": "Invitation sent successfully",
  "invitation": {
    "id": "uuid-token",
    "team_slug": "demo-team",
    "email": "user@example.com",
    "role": "member",
    "expires_at": "2025-09-10T03:09:07.324134",
    "status": "pending"
  }
}

Accept/Decline Invitation

POST /api/invitations/{token}

Purpose: Accept or decline a team invitation

Headers: Authorization: Bearer {token}

Request Body:
{
  "action": "accept"
}

User Team Information

Get Current User's Teams

GET /api/user/teams PERFECT FOR MULTI-TENANCY

Purpose: Get all teams the current user belongs to (essential for multi-tenant apps)

Headers: Authorization: Bearer {token}

💡 Multi-Tenant Tip: Use this endpoint to determine which "tenants" (teams) the user can access in your application.
Response Format:
{
  "teams": [
    {
      "id": 1,
      "name": "Demo Team",
      "slug": "demo-team",
      "description": "A demo team for testing",
      "user_membership": {
        "id": 5,
        "team_id": 1,
        "user_id": 29,
        "role": "admin",
        "status": "active",
        "joined_at": "2025-09-03T03:09:07.324134"
      }
    }
  ]
}

Get User's Pending Invitations

GET /api/user/invitations

Purpose: Get all pending team invitations for current user

Headers: Authorization: Bearer {token}

Multi-Tenant Implementation Example

Perfect for applications that need team-based access control:

Example: Multi-Tenant Finance App
// After user authenticates with Hub SSO
app.get('/sso/callback', async (req, res) => {
  const { token } = req.query;
  
  // 1. Validate user with Hub
  const userResponse = await fetch('https://hub.regardingwork.com/api/auth/validate', {
    headers: { 'Authorization': `Bearer ${token}` }
  });
  const userData = await userResponse.json();
  
  // 2. Get user's teams (their "tenants")  
  const teamsResponse = await fetch('https://hub.regardingwork.com/api/user/teams', {
    headers: { 'Authorization': `Bearer ${token}` }
  });
  const teamsData = await teamsResponse.json();
  
  // 3. User can access multiple tenants
  const userTenants = teamsData.teams.map(team => ({
    tenantId: team.slug,           // "acme-corp", "family-budget"
    tenantName: team.name,         // "Acme Corporation"
    role: team.user_membership.role, // "admin" or "member"
    teamId: team.id
  }));
  
  // 4. Set session with multi-tenant context
  req.session.user = userData;
  req.session.tenants = userTenants;
  req.session.activeTenant = userTenants[0]; // Default to first
  
  res.redirect('/dashboard');
});
Quick Links
← Back to Main Docs Authentication API Integration Guide Troubleshooting