Team Management

​

Overview

​

Organization Structure

​

Hierarchy

Organization
├── Members (users with roles)
├── Projects
│   ├── API Keys
│   └── Provider Keys
└── Billing Settings

​

Organization Types

​

Personal Organizations

• Automatically created for each user
• Single owner (the user)
• Can invite team members
• Billed to owner’s account

​

Team Organizations

• Created explicitly by users
• Multiple members with different roles
• Shared billing
• Collaborative workspace

​

User Roles

​

Role Hierarchy

​

Member Management

​

Adding Members

​

Email Invitation

import { inviteMember } from '@/lib/organizations';

const invitation = await inviteMember({
  organizationId: 'org_123',
  email: '[email protected]',
  role: 'member'
});

​

Invitation Flow

1. Owner/admin enters email and selects role
2. System sends invitation email
3. Recipient clicks invitation link
4. If they have an account: added immediately
5. If new user: prompted to create account first
6. User is added to organization with specified role

​

Removing Members

import { removeMember } from '@/lib/organizations';

await removeMember({
  organizationId: 'org_123',
  userId: 'user_456'
});

​

Changing Roles

import { updateMemberRole } from '@/lib/organizations';

await updateMemberRole({
  organizationId: 'org_123',
  userId: 'user_456',
  newRole: 'admin'
});

​

Membership Database Schema

​

Member Table

CREATE TABLE member (
  id TEXT PRIMARY KEY,
  user_id TEXT NOT NULL REFERENCES "user"(id) ON DELETE CASCADE,
  organization_id TEXT NOT NULL REFERENCES organization(id) ON DELETE CASCADE,
  role TEXT NOT NULL, -- owner, admin, member, viewer
  created_at TIMESTAMP NOT NULL DEFAULT NOW(),
  UNIQUE(user_id, organization_id)
);

​

Invitation Table

CREATE TABLE invitation (
  id TEXT PRIMARY KEY,
  organization_id TEXT NOT NULL REFERENCES organization(id) ON DELETE CASCADE,
  email TEXT NOT NULL,
  role TEXT NOT NULL,
  token TEXT NOT NULL UNIQUE,
  expires_at TIMESTAMP NOT NULL,
  created_at TIMESTAMP NOT NULL DEFAULT NOW(),
  created_by TEXT NOT NULL REFERENCES "user"(id),
  status TEXT NOT NULL -- pending, accepted, expired, cancelled
);

​

Permission System

​

Checking Permissions

import { checkPermission } from '@/lib/permissions';

const canManageBilling = await checkPermission({
  userId: 'user_123',
  organizationId: 'org_456',
  action: 'billing:manage'
});

​

Permission Matrix

​

Team Dashboard

​

Member List

• Name and email
• Role badge
• Join date
• Last active
• Actions (change role, remove)

​

Activity Feed

• Member joined
• Member removed
• Role changed
• Project created
• API key generated
• Settings updated

​

Usage by Member

• Requests made
• Tokens consumed
• Cost incurred
• API keys created

​

Collaboration Features

​

Shared Projects

// List accessible projects
const projects = await getProjects({
  organizationId: 'org_123'
});

​

Shared Analytics

• Organization-wide metrics
• Per-project analytics
• Cost breakdowns
• Usage trends

​

Shared Playground

• Test prompts collaboratively
• Share playground sessions
• Save and reuse prompts
• Compare model outputs

​

API Integration

​

Member Endpoints

// List members
GET /organizations/:orgId/members

// Invite member
POST /organizations/:orgId/members/invite
Body: { email, role }

// Update role
PATCH /organizations/:orgId/members/:userId
Body: { role }

// Remove member
DELETE /organizations/:orgId/members/:userId

​

Invitation Endpoints

// List pending invitations
GET /organizations/:orgId/invitations

// Cancel invitation
DELETE /organizations/:orgId/invitations/:invitationId

// Accept invitation
POST /invitations/:token/accept

​

Best Practices

​

Role Assignment

1. Start restrictive - Assign viewer or member initially
2. Promote as needed - Upgrade to admin when trust is established
3. Limit owners - Keep only one owner when possible
4. Regular audits - Review roles quarterly

​

Onboarding

1. Send invitation with welcome message
2. Provide documentation links
3. Share relevant projects
4. Set up 1-on-1 walkthrough
5. Grant appropriate access level

​

Offboarding

1. Remove from organization
2. Revoke API keys if shared
3. Update documentation access
4. Archive their projects if needed
5. Document handoff

​

Security

• Use least privilege principle
• Audit member list regularly
• Monitor for unusual activity
• Rotate shared credentials
• Enable 2FA for owners/admins

​

Team Limits

​

Free Plan

• 1 owner (automatic)
• No additional members
• Personal projects only

​

Pro Plan

• 1 owner
• Up to 10 members
• Unlimited viewers
• Shared projects

​

Enterprise Plan

• Custom member limits
• Advanced role customization
• SSO integration
• Audit logging
• Dedicated support

​

Audit Trail

​

Member Actions

interface AuditLog {
  action: 'member.invite' | 'member.remove' | 'member.role_change';
  actorUserId: string;
  targetUserId: string;
  organizationId: string;
  metadata: {
    oldRole?: string;
    newRole?: string;
    email?: string;
  };
  timestamp: Date;
}

​

Viewing Audit Logs

const logs = await getAuditLogs({
  organizationId: 'org_123',
  resourceType: 'member',
  limit: 50
});

​

SSO Integration (Enterprise)

​

Supported Providers

• Google Workspace
• Microsoft Azure AD
• Okta
• Auth0
• SAML 2.0

​

Configuration

await configureSSOProvider({
  organizationId: 'org_123',
  provider: 'google-workspace',
  domain: 'yourcompany.com',
  clientId: 'client_id',
  clientSecret: 'client_secret'
});

​

Auto-Provisioning

• Users from verified domain auto-join
• Assigned default role (configurable)
• No invitation needed
• Deprovisioning on SSO removal

​

Troubleshooting

​

Invitation Not Received

1. Check spam folder
2. Verify email address spelling
3. Resend invitation
4. Check invitation status in dashboard

​

Can’t Remove Member

• Ensure you’re an owner or admin
• Can’t remove yourself (transfer ownership first)
• Can’t remove the only owner

​

Permission Denied

• Verify your role has required permissions
• Check if organization is active
• Contact organization owner
• Review audit logs for role changes

​

Member Limit Reached

• Upgrade to higher plan
• Remove inactive members
• Contact sales for custom limits