Teams and Roles

Teams are the primary mechanism for granting users access to projects in Topographer. By organizing users into teams and assigning roles, you can control who has access to which projects and what actions they can perform.

Understanding Teams

A Team is a group of users that share the same level of access to a set of projects. Each team has:

  • Members: The users who belong to the team
  • Roles: The permissions granted to team members
  • Projects: The projects the team can access
Teams list showing organization teams

System Teams

Every organization starts with two special system teams that cannot be deleted:

TeamDescription
AdminsFull administrative access to the organization. Members can manage teams, users, projects, and organization settings.
MembersStandard access for regular users. The default team for organization members.
ℹ️ New User Assignment

When inviting new users, you must select which team(s) to add them to. New users are not automatically added to the Members team.

Creating Teams

To create a new team:

  1. Navigate to Organization → Teams
  2. Click Create Team
  3. Enter a team name
  4. Click Create

After creating the team, you’ll be taken to the team detail page where you can configure roles, project access, and add members.

Create team dialog

Roles

Roles define what actions team members can perform. Topographer provides three built-in roles:

RoleDescription
ViewerRead-only access. Can view projects, artifacts, and reports but cannot make changes.
MemberStandard access. Can view and interact with projects, run queries, and access most features.
AdminFull access. Can manage projects, teams, users, and organization settings.

Each role includes all permissions of the roles below it (Admin includes Member permissions, Member includes Viewer permissions).

💡 Admins Team vs Admin Role

“Admin” refers to both the system team (Admins) and a role (Admin). The Admins team has the Admin role assigned by default, giving its members full administrative privileges.

Team-Project Access Model

Teams control which projects their members can access. There are two ways to configure project access:

All Projects Access

A team can be granted access to all projects in the organization. This is useful for:

  • Organization administrators who need access to everything
  • Cross-functional teams that work across all projects

When new projects are created, teams with “all projects” access automatically gain access to them.

Specific Project Access

A team can be granted access to specific projects. This is useful for:

  • Project-specific teams
  • Contractors or external collaborators with limited scope
  • Teams that should only see certain projects
Team project access configuration

Multiple Teams for Different Access Levels

If you need to grant different permission levels to different projects, create multiple teams. For example:

  • Frontend Team - Member role on frontend projects
  • Backend Team - Member role on backend projects
  • DevOps Team - Admin role on infrastructure projects

A user can belong to multiple teams, and their effective permissions are the combination of all their team memberships.

Managing Teams

Viewing Team Details

Click on a team to view:

  • Team members
  • Assigned roles
  • Project access configuration
Team detail page showing members, roles, and projects

Adding Users to Teams

  1. Navigate to the team detail page
  2. Click Add Member
  3. Select the user(s) to add
  4. Click Add

Removing Users from Teams

  1. Navigate to the team detail page
  2. Find the user in the members list
  3. Click the remove button next to their name
  4. Confirm the removal

Modifying Team Access

  1. Navigate to the team detail page
  2. Update the roles or project access as needed
  3. Changes take effect immediately

Permissions

Permissions in Topographer are enforced throughout the dashboard and API. The permission system ensures users can only access features and data appropriate to their role.

How Permissions Work

  1. Users are assigned to one or more teams
  2. Each team has roles that grant specific permissions
  3. When a user attempts an action, Topographer checks if any of their teams grant the required permission
  4. If permitted, the action proceeds; otherwise, the feature is hidden or the action is blocked

Permission Inheritance

Permissions flow from teams to users:

Organization
  └── Team (with Roles)
        └── User (inherits team permissions)
              └── Project Access (from team configuration)

API Token Permissions

When you create an API token, it inherits your current permissions. The token cannot have more permissions than you do—it’s limited to what you can access at the time of creation.

Best Practices

  1. Use descriptive team names that reflect the team’s purpose or the projects they access
  2. Follow least privilege - grant only the permissions users need
  3. Review team membership regularly to ensure access is current
  4. Use specific project access when possible rather than “all projects” access
  5. Document your team structure so others understand the access model

What’s Next?