Creates a new group within an organization.

Use this method to:

• Create teams for access control
• Organize users by department or function
• Set up role-based access groups

Examples

• Create a basic group:

  Creates a group with name and description.

  organizationId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
  name: "Backend Team"
  description: "Backend engineering team"
  

Authorization

Requires org:admin role on the organization.

Deletes a group and removes all its resource assignments.

When a group is deleted, all resource assignments revert to org-level scope.

Use this method to:

• Remove unused groups
• Clean up after team reorganization

Examples

• Delete a group:

  Permanently removes a group.

  groupId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
  

Authorization

Requires org:admin role on the organization.

Lists groups with optional pagination.

Use this method to:

• View all groups in an organization
• Check group memberships
• Monitor group configurations
• Audit group access

Examples

• List all groups:

  Shows all groups with pagination.

  pagination:
    pageSize: 20
  

• List with custom page size:

  Shows groups with specified page size.

  pagination:
    pageSize: 50
    token: "next-page-token-from-previous-response"
  

Authorization

All organization members can list groups (transparency model).

Gets information about a specific group.

Use this method to:

• Retrieve group details and metadata
• Check group configuration
• View member count

Examples

• Get group details:

  Retrieves information about a specific group.

  groupId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
  

Authorization

All organization members can view group information (transparency model).

Updates group information.

Use this method to:

• Rename a group
• Update group description

Examples

• Update group name:

  Changes the name of an existing group.

  groupId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
  name: "Platform Team"
  description: "Platform engineering team"
  

Authorization

Requires org:admin permission on the organization or group:admin permission on the specific group.

Creates a membership for a user in a group.

Use this method to:

• Add users to groups
• Grant group-based permissions to users

Examples

• Add a user to a group:

  Creates a membership for a user in a group.

  groupId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
  subject:
    id: "f53d2330-3795-4c5d-a1f3-453121af9c60"
    principal: PRINCIPAL_USER
  

Authorization

Requires org:admin permission on the organization or group:admin permission on the specific group.

Deletes a membership for a user in a group.

Use this method to:

• Remove users from groups
• Revoke group-based permissions

Examples

• Remove a user from a group:

  Deletes a membership by its ID.

  membershipId: "a1b2c3d4-5678-90ab-cdef-1234567890ab"
  

Authorization

Requires org:admin permission on the organization or group:admin permission on the specific group.

Lists all memberships of a group.

Use this method to:

• View all members of a group
• Audit group membership

Examples

• List group members:

  Shows all members of a specific group.

  groupId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
  pagination:
    pageSize: 20
  

Authorization

All organization members can view group membership (transparency model).

Gets a specific membership by group ID and subject.

Use this method to:

• Check if a user or service account is a member of a group
• Verify group membership for access control

Examples

• Check user membership:

  Checks if a user is a member of a specific group.

  groupId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
  subject:
    id: "f53d2330-3795-4c5d-a1f3-453121af9c60"
    principal: PRINCIPAL_USER
  

Authorization

All organization members can check group membership (transparency model).

Creates a role assignment for a group on a resource.

Use this method to:

• Assign specific roles to groups on runners, projects, or environments
• Grant group-based access to resources

Examples

• Assign admin role on a runner:

  Grants the group admin access to a runner.

  groupId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
  resourceType: RESOURCE_TYPE_RUNNER
  resourceId: "f53d2330-3795-4c5d-a1f3-453121af9c60"
  resourceRole: RESOURCE_ROLE_RUNNER_ADMIN
  

• Assign user role on a project:

  Grants the group user access to a project.

  groupId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
  resourceType: RESOURCE_TYPE_PROJECT
  resourceId: "a1b2c3d4-5678-90ab-cdef-1234567890ab"
  resourceRole: RESOURCE_ROLE_PROJECT_USER
  

Authorization

Requires admin role on the specific resource.

Deletes a role assignment.

Use this method to:

• Remove group access to resources
• Revoke role-based permissions

Examples

• Delete a role assignment:

  Removes a role assignment by its ID.

  assignmentId: "a1b2c3d4-5678-90ab-cdef-1234567890ab"
  

Authorization

Requires admin role on the specific resource.

Lists role assignments for a group or resource.

Use this method to:

• View all role assignments for a group
• Audit resource access
• Check which groups have access to resources

Examples

• List role assignments for a group:

  Shows all role assignments for a specific group.

  filter:
    groupId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
  pagination:
    pageSize: 20
  

• List role assignments by resource type:

  Shows all role assignments for runners.

  filter:
    resourceTypes:
      - RESOURCE_TYPE_RUNNER
  pagination:
    pageSize: 20
  

Authorization

All organization members can view role assignments (transparency model).

Shares a resource directly with a principal (user or service account).

Use this method to:

• Grant a user or service account direct access to a runner, project, or other resource
• Share resources without creating and managing groups manually

Examples

• Share a runner with a user:

  Grants admin access to a runner for a specific user.

  resourceType: RESOURCE_TYPE_RUNNER
  resourceId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
  principal: PRINCIPAL_USER
  principalId: "f53d2330-3795-4c5d-a1f3-453121af9c60"
  role: RESOURCE_ROLE_RUNNER_ADMIN
  

• Share a runner with a service account:

  Grants user access to a runner for a service account.

  resourceType: RESOURCE_TYPE_RUNNER
  resourceId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
  principal: PRINCIPAL_SERVICE_ACCOUNT
  principalId: "a1b2c3d4-5678-90ab-cdef-1234567890ab"
  role: RESOURCE_ROLE_RUNNER_USER
  

Authorization

Requires admin role on the specific resource.

Removes direct access for a principal (user or service account) from a resource.

Use this method to:

• Revoke a principal's direct access to a resource
• Remove sharing without affecting group-based access

Examples

• Remove user access from a runner:

  Revokes a user's direct access to a runner.

  resourceType: RESOURCE_TYPE_RUNNER
  resourceId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
  principal: PRINCIPAL_USER
  principalId: "f53d2330-3795-4c5d-a1f3-453121af9c60"
  

Authorization

Requires admin role on the specific resource.