Skip to main content

User Memberships

Users can belong to multiple organizations within a tenant, each with different roles and permissions.

Membership Model​

interface OrganizationMembership {
  id: string;
  userId: string;
  organizationId: string;
  createdAt: Date;
  organization: Organization;
  roleAssignments: RoleAssignment[];
}

Get User's Organizations​

List all organizations a user belongs to.

Endpoint​

GET /users/:id/organizations

Response (200 OK)​

{
  "data": [
    {
      "id": "mem-001",
      "organizationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "organization": {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "name": "Engineering",
        "slug": "engineering"
      },
      "roleAssignments": [
        {
          "id": "ra-001",
          "roleId": "org-admin-id",
          "role": {
            "id": "org-admin-id",
            "name": "ORG_ADMIN"
          }
        }
      ]
    },
    {
      "id": "mem-002",
      "organizationId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "organization": {
        "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
        "name": "Project Alpha",
        "slug": "project-alpha"
      },
      "roleAssignments": [
        {
          "id": "ra-002",
          "roleId": "member-id",
          "role": {
            "id": "member-id",
            "name": "MEMBER"
          }
        }
      ]
    }
  ]
}

Get User's Roles​

List all role assignments for a user.

Endpoint​

GET /users/:id/roles

Response (200 OK)​

{
  "data": [
    {
      "id": "ra-001",
      "roleId": "tenant-admin-id",
      "organizationId": null,
      "role": {
        "id": "tenant-admin-id",
        "name": "TENANT_ADMIN",
        "scopeLevel": "TENANT"
      },
      "createdAt": "2024-01-01T00:00:00.000Z"
    },
    {
      "id": "ra-002",
      "roleId": "org-admin-id",
      "organizationId": "engineering-org-id",
      "role": {
        "id": "org-admin-id",
        "name": "ORG_ADMIN",
        "scopeLevel": "ORGANIZATION"
      },
      "organization": {
        "id": "engineering-org-id",
        "name": "Engineering"
      },
      "createdAt": "2024-01-05T00:00:00.000Z"
    }
  ]
}

Add User to Organization​

Assign a role to a user within an organization.

Endpoint​

POST /role-assignments

Request​

{
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "roleId": "member-role-id",
  "organizationId": "engineering-org-id"
}

Response (201 Created)​

{
  "id": "ra-003",
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "roleId": "member-role-id",
  "organizationId": "engineering-org-id",
  "createdAt": "2024-01-15T10:30:00.000Z"
}

Remove User from Organization​

Revoke a role assignment.

Endpoint​

DELETE /role-assignments/:id

Response (204 No Content)​

Multiple Roles in One Organization​

A user can have multiple roles in the same organization:

{
  "userId": "user-id",
  "organizationId": "engineering-org-id",
  "roles": [
    { "name": "MEMBER" },
    { "name": "PROJECT_LEAD" }
  ]
}

Code Examples​

TypeScript​

interface Membership {
  organizationId: string;
  organization: {
    id: string;
    name: string;
  };
  roleAssignments: {
    id: string;
    roleId: string;
    role: {
      id: string;
      name: string;
    };
  }[];
}

class MembershipManager {
  constructor(private accessToken: string) {}

  async getUserOrganizations(userId: string): Promise<Membership[]> {
    const response = await fetch(
      `http://localhost:8091/users/${userId}/organizations`,
      {
        headers: {
          'Authorization': `Bearer ${this.accessToken}`,
        },
      }
    );
    const data = await response.json();
    return data.data;
  }

  async addToOrganization(
    userId: string,
    organizationId: string,
    roleId: string
  ): Promise<void> {
    await fetch('http://localhost:8091/role-assignments', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${this.accessToken}`,
      },
      body: JSON.stringify({
        userId,
        organizationId,
        roleId,
      }),
    });
  }

  async removeFromOrganization(roleAssignmentId: string): Promise<void> {
    await fetch(
      `http://localhost:8091/role-assignments/${roleAssignmentId}`,
      {
        method: 'DELETE',
        headers: {
          'Authorization': `Bearer ${this.accessToken}`,
        },
      }
    );
  }
}

// Usage
const manager = new MembershipManager(accessToken);

// Get user's organizations
const memberships = await manager.getUserOrganizations('user-id');
console.log('Organizations:', memberships.map(m => m.organization.name));

// Add user to organization
await manager.addToOrganization('user-id', 'sales-org-id', 'member-role-id');

cURL​

# Get user's organizations
curl http://localhost:8091/users/550e8400-e29b-41d4-a716-446655440000/organizations \
  -H "Authorization: Bearer <access-token>"

# Get user's roles
curl http://localhost:8091/users/550e8400-e29b-41d4-a716-446655440000/roles \
  -H "Authorization: Bearer <access-token>"

# Add user to organization with role
curl -X POST http://localhost:8091/role-assignments \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access-token>" \
  -d '{
    "userId": "550e8400-e29b-41d4-a716-446655440000",
    "roleId": "member-role-id",
    "organizationId": "engineering-org-id"
  }'

# Remove user from organization
curl -X DELETE http://localhost:8091/role-assignments/ra-001 \
  -H "Authorization: Bearer <access-token>"

Best Practices​

1. Least Privilege​

Assign the minimum required role for each organization.

2. Regular Review​

Periodically review user memberships and remove unnecessary access.

3. Use Groups (Future)​

When available, use groups to manage memberships at scale.

4. Audit Changes​

All membership changes are logged in the audit trail.