List/View Teams

Listing and viewing teams in Nexla allows you to understand your team structure, manage team memberships, and organize access control across your organization. The system provides flexible endpoints for viewing teams based on ownership and membership.

List Teams You Own

Listing teams you own allows you to see all teams under your management and control. This is useful for understanding your administrative responsibilities and managing team configurations.

Ownership Endpoint

Make a GET request to the /teams endpoint to list all of the teams owned by the authenticated user. A successful request returns with status 200 and a JSON response containing an array of team objects.

Request

To retrieve teams you own:

GET /teams

Nexla API

List Teams You Own: Request

GET /teams

Response

The response includes comprehensive team information including ownership details, membership, and configuration.

Nexla API

List Teams You Own: Response

[
  {
    "id": 1001,
    "owner": {
      "id": 42,
      "full_name": "John Smith",
      "email": "john.smith@example.com",
      "email_verified_at": "2023-01-15T10:30:00.000Z"
    },
    "org": {
      "id": 101,
      "name": "Acme Corporation",
      "cluster_id": "cluster-123",
      "new_cluster_id": "cluster-456",
      "cluster_status": "active",
      "status": "active",
      "email_domain": "acme.com",
      "email": null,
      "client_identifier": "acme-client",
      "self_signup": false,
      "features_enabled": ["feature1", "feature2"],
      "org_tier": {
        "id": 1,
        "name": "Enterprise"
      }
    },
    "member": false,
    "access_roles": ["owner"],
    "name": "Testing Team",
    "description": "Team for testing and development",
    "members": [
      {
        "id": 43,
        "email": "jane.doe@example.com",
        "admin": true
      }
    ],
    "tags": ["testing", "development"],
    "updated_at": "2023-01-15T17:12:06.000Z",
    "created_at": "2023-01-15T17:12:06.000Z"
  },
  {
    "id": 1002,
    "owner": {
      "id": 42,
      "full_name": "John Smith",
      "email": "john.smith@example.com",
      "email_verified_at": "2023-01-15T10:30:00.000Z"
    },
    "org": {
      "id": 101,
      "name": "Acme Corporation",
      "cluster_id": "cluster-123",
      "new_cluster_id": "cluster-456",
      "cluster_status": "active",
      "status": "active",
      "email_domain": "acme.com",
      "email": null,
      "client_identifier": "acme-client",
      "self_signup": false,
      "features_enabled": ["feature1", "feature2"],
      "org_tier": {
        "id": 1,
        "name": "Enterprise"
      }
    },
    "member": true,
    "access_roles": ["member", "owner"],
    "name": "Example Team",
    "description": "A team with two members",
    "members": [
      {
        "id": 42,
        "email": "john.smith@example.com",
        "admin": true
      },
      {
        "id": 44,
        "email": "bob.wilson@example.com",
        "admin": true
      }
    ],
    "tags": ["example", "collaboration"],
    "updated_at": "2023-01-15T19:20:01.000Z",
    "created_at": "2023-01-15T19:20:01.000Z"
  }
]

List Teams You Belong To

Listing teams you belong to allows you to see all teams where you have membership, regardless of ownership. This is useful for understanding your access rights and team participation.

Membership Endpoint

Set the access_role query parameter to member when making a GET request to the /teams endpoint to list only the teams the requester is a member of.

List Member Teams Request

To retrieve teams you belong to:

GET /teams?access_role=member

Nexla API

List Teams You Belong To: Request

GET /teams?access_role=member

Member Teams Response

The response includes teams where you have membership, showing your role and access level in each team.

List All Accessible Teams

You can also list all teams you have access to, combining both owned and member teams in a single request.

All Teams Endpoint

To retrieve all accessible teams:

GET /teams?access_role=all

Nexla API

List Teams You Own: Request

GET /teams?access_role=owner

All Teams Response

This response includes all teams you can access, providing a comprehensive view of your team relationships.

Team Information Fields

The team listing responses include several important fields that help you understand and manage your teams:

Basic Information

• id: Unique identifier for the team
• name: Descriptive name for the team
• description: Optional description of the team's purpose
• created_at: When the team was created
• updated_at: When the team was last modified

Ownership and Organization

• owner: User who owns and can manage the team
• org: Organization the team belongs to (if any)
• access_roles: Your current access level to this team

Membership Details

• member: Whether you are a member of this team
• members: List of current team members with their roles
• admin: Whether members have administrative privileges

Team Access Roles

Teams support different access levels that determine your capabilities:

Owner

• Full Control: Complete team management capabilities
• Member Management: Add, remove, and modify team members
• Team Configuration: Update team settings and properties
• Resource Access: Grant team access to resources

Admin

• Member Management: Add and modify team members
• Team Operations: Perform team-related operations
• Limited Configuration: Some team setting modifications

Member

• Resource Access: Access to team-granted resources
• Team Participation: Participate in team activities
• Read Access: View team information and membership

Filtering and Pagination

You can use query parameters to filter and paginate team results:

Access Role Filtering

GET /teams?access_role=owner
GET /teams?access_role=member
GET /teams?access_role=all

Pagination

GET /teams?page=1&per_page=50

Team Organization

Understanding your team structure helps with effective management:

Owned Teams

Teams you own provide administrative control and management capabilities. These are typically teams you've created for specific purposes or projects.

Member Teams

Teams you belong to provide access to shared resources and collaborative workflows. These teams may have been created by others but include you as a member.

Organization Teams

Teams within your organization provide structured access control and resource management. These teams follow organizational boundaries and policies.

Best Practices

To effectively list and view teams:

1. Regular Review: Periodically review your team memberships and ownership
2. Access Monitoring: Monitor which teams have access to sensitive resources
3. Documentation: Maintain clear documentation of team purposes and responsibilities
4. Permission Auditing: Regularly audit team permissions and access levels
5. Cleanup: Remove yourself from teams you no longer need to belong to

Error Handling

Common team listing issues and solutions:

• Permission Denied: Ensure you have appropriate access rights
• Invalid Parameters: Check query parameter values and formats
• Organization Issues: Verify organization membership and access
• Authentication Problems: Ensure proper authentication and API keys

Related Operations

After listing teams, you may need to:

View Team Details

GET /teams/{team_id}

Manage Team Members

GET /teams/{team_id}/members
PUT /teams/{team_id}/members

Update Team Settings

PUT /teams/{team_id}

Control Resource Access

GET /teams/{team_id}/access
GET /teams/{team_id}/accessors
POST /teams/{team_id}/accessors
PUT /teams/{team_id}/accessors
DELETE /teams/{team_id}/accessors