Skip to content
Ona API Reference
Ona Docs
API Reference
Groups
Role Assignments

ListRoleAssignments

POST/gitpod.v1.GroupService/ListRoleAssignments

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).

Query ParametersExpand Collapse
token: optional string
pageSize: optional number
maximum100
minimum0
Body ParametersJSONExpand Collapse
filter: optional object { groupId, resourceId, resourceIds, 3 more }

Filter parameters

groupId: optional string

group_id filters the response to only role assignments for this specific group Empty string is allowed and means no filtering by group

resourceId: optional string

Filters by a single resource. Non-admin callers with :grant permission on the resource can see role assignments from groups they don’t belong to. Mutually exclusive with resource_ids.

resourceIds: optional array of string

Filters by multiple resources in a single request. Non-admin callers with :grant permission on a resource can see all role assignments for that resource, even from groups they don’t belong to. The :grant check is applied per-resource within the batch. Mutually exclusive with resource_id.

resourceRoles: optional array of ResourceRole

resource_roles filters the response to only role assignments with these specific roles

One of the following:
"RESOURCE_ROLE_UNSPECIFIED"
"RESOURCE_ROLE_ORG_ADMIN"
"RESOURCE_ROLE_ORG_MEMBER"
"RESOURCE_ROLE_ORG_RUNNERS_ADMIN"
"RESOURCE_ROLE_ORG_PROJECTS_ADMIN"
"RESOURCE_ROLE_ORG_AUTOMATIONS_ADMIN"
"RESOURCE_ROLE_ORG_GROUPS_ADMIN"
"RESOURCE_ROLE_ORG_AUDIT_LOG_READER"
"RESOURCE_ROLE_GROUP_ADMIN"
"RESOURCE_ROLE_GROUP_VIEWER"
"RESOURCE_ROLE_USER_IDENTITY"
"RESOURCE_ROLE_USER_VIEWER"
"RESOURCE_ROLE_USER_ADMIN"
"RESOURCE_ROLE_ENVIRONMENT_IDENTITY"
"RESOURCE_ROLE_ENVIRONMENT_ADMIN"
"RESOURCE_ROLE_ENVIRONMENT_USER"
"RESOURCE_ROLE_ENVIRONMENT_VIEWER"
"RESOURCE_ROLE_ENVIRONMENT_RUNNER"
"RESOURCE_ROLE_RUNNER_IDENTITY"
"RESOURCE_ROLE_RUNNER_ADMIN"
"RESOURCE_ROLE_RUNNER_LOCAL_ADMIN"
"RESOURCE_ROLE_RUNNER_MANAGED_ADMIN"
"RESOURCE_ROLE_RUNNER_USER"
"RESOURCE_ROLE_RUNNER_CONFIGURATION_READER"
"RESOURCE_ROLE_HOST_AUTHENTICATION_TOKEN_ADMIN"
"RESOURCE_ROLE_HOST_AUTHENTICATION_TOKEN_UPDATER"
"RESOURCE_ROLE_PROJECT_ADMIN"
"RESOURCE_ROLE_PROJECT_USER"
"RESOURCE_ROLE_PROJECT_EDITOR"
"RESOURCE_ROLE_ENVIRONMENT_SERVICE_ADMIN"
"RESOURCE_ROLE_ENVIRONMENT_SERVICE_VIEWER"
"RESOURCE_ROLE_ENVIRONMENT_SERVICE_USER"
"RESOURCE_ROLE_ENVIRONMENT_SERVICE_ENV"
"RESOURCE_ROLE_ENVIRONMENT_TASK_ADMIN"
"RESOURCE_ROLE_ENVIRONMENT_TASK_VIEWER"
"RESOURCE_ROLE_ENVIRONMENT_TASK_USER"
"RESOURCE_ROLE_ENVIRONMENT_TASK_ENV"
"RESOURCE_ROLE_SERVICE_ACCOUNT_IDENTITY"
"RESOURCE_ROLE_SERVICE_ACCOUNT_ADMIN"
"RESOURCE_ROLE_AGENT_EXECUTION_USER"
"RESOURCE_ROLE_AGENT_EXECUTION_ADMIN"
"RESOURCE_ROLE_AGENT_EXECUTION_RUNNER"
"RESOURCE_ROLE_AGENT_EXECUTION_OUTPUTS_REPORTER"
"RESOURCE_ROLE_AGENT_EXECUTION_VIEWER"
"RESOURCE_ROLE_AGENT_ADMIN"
"RESOURCE_ROLE_AGENT_VIEWER"
"RESOURCE_ROLE_AGENT_EXECUTOR"
"RESOURCE_ROLE_WORKFLOW_ADMIN"
"RESOURCE_ROLE_WORKFLOW_USER"
"RESOURCE_ROLE_WORKFLOW_VIEWER"
"RESOURCE_ROLE_WORKFLOW_EXECUTOR"
"RESOURCE_ROLE_SNAPSHOT_ADMIN"
"RESOURCE_ROLE_SNAPSHOT_RUNNER"
"RESOURCE_ROLE_WEBHOOK_ADMIN"
"RESOURCE_ROLE_WEBHOOK_VIEWER"
"RESOURCE_ROLE_WARMPOOL_RUNNER"
"RESOURCE_ROLE_WARMPOOL_ADMIN"
"RESOURCE_ROLE_WARMPOOL_VIEWER"
"RESOURCE_ROLE_SESSION_ADMIN"
"RESOURCE_ROLE_SESSION_USER"
"RESOURCE_ROLE_TEAM_ADMIN"
"RESOURCE_ROLE_TEAM_VIEWER"
resourceTypes: optional array of ResourceType

resource_types filters the response to only role assignments for these resource types

One of the following:
"RESOURCE_TYPE_UNSPECIFIED"
"RESOURCE_TYPE_ENVIRONMENT"
"RESOURCE_TYPE_RUNNER"
"RESOURCE_TYPE_PROJECT"
"RESOURCE_TYPE_TASK"
"RESOURCE_TYPE_TASK_EXECUTION"
"RESOURCE_TYPE_SERVICE"
"RESOURCE_TYPE_ORGANIZATION"
"RESOURCE_TYPE_USER"
"RESOURCE_TYPE_ENVIRONMENT_CLASS"
"RESOURCE_TYPE_RUNNER_SCM_INTEGRATION"
"RESOURCE_TYPE_HOST_AUTHENTICATION_TOKEN"
"RESOURCE_TYPE_GROUP"
"RESOURCE_TYPE_PERSONAL_ACCESS_TOKEN"
"RESOURCE_TYPE_USER_PREFERENCE"
"RESOURCE_TYPE_SERVICE_ACCOUNT"
"RESOURCE_TYPE_SECRET"
"RESOURCE_TYPE_SSO_CONFIG"
"RESOURCE_TYPE_DOMAIN_VERIFICATION"
"RESOURCE_TYPE_AGENT_EXECUTION"
"RESOURCE_TYPE_RUNNER_LLM_INTEGRATION"
"RESOURCE_TYPE_AGENT"
"RESOURCE_TYPE_ENVIRONMENT_SESSION"
"RESOURCE_TYPE_USER_SECRET"
"RESOURCE_TYPE_ORGANIZATION_POLICY"
"RESOURCE_TYPE_ORGANIZATION_SECRET"
"RESOURCE_TYPE_PROJECT_ENVIRONMENT_CLASS"
"RESOURCE_TYPE_BILLING"
"RESOURCE_TYPE_PROMPT"
"RESOURCE_TYPE_COUPON"
"RESOURCE_TYPE_COUPON_REDEMPTION"
"RESOURCE_TYPE_ACCOUNT"
"RESOURCE_TYPE_INTEGRATION"
"RESOURCE_TYPE_WORKFLOW"
"RESOURCE_TYPE_WORKFLOW_EXECUTION"
"RESOURCE_TYPE_WORKFLOW_EXECUTION_ACTION"
"RESOURCE_TYPE_SNAPSHOT"
"RESOURCE_TYPE_PREBUILD"
"RESOURCE_TYPE_ORGANIZATION_LLM_INTEGRATION"
"RESOURCE_TYPE_CUSTOM_DOMAIN"
"RESOURCE_TYPE_ROLE_ASSIGNMENT_CHANGED"
"RESOURCE_TYPE_GROUP_MEMBERSHIP_CHANGED"
"RESOURCE_TYPE_WEBHOOK"
"RESOURCE_TYPE_SCIM_CONFIGURATION"
"RESOURCE_TYPE_SERVICE_ACCOUNT_SECRET"
"RESOURCE_TYPE_ANNOUNCEMENT_BANNER"
"RESOURCE_TYPE_SERVICE_ACCOUNT_TOKEN"
"RESOURCE_TYPE_ROLE_ASSIGNMENT"
"RESOURCE_TYPE_WARM_POOL"
"RESOURCE_TYPE_NOTIFICATION"
userId: optional string

user_id filters the response to only role assignments for groups that this user is a member of Empty string is allowed and means no filtering by user

ReturnsExpand Collapse
assignments: optional array of RoleAssignment { id, derivedFromOrgRole, groupId, 4 more }
id: optional string

Unique identifier for the role assignment

formatuuid
derivedFromOrgRole: optional ResourceRole

The org-level role that created this assignment, if any. RESOURCE_ROLE_UNSPECIFIED means this is a direct share (manually created). Non-zero (e.g., ORG_PROJECTS_ADMIN, ORG_RUNNERS_ADMIN) means this assignment was derived from an org-level role.

One of the following:
"RESOURCE_ROLE_UNSPECIFIED"
"RESOURCE_ROLE_ORG_ADMIN"
"RESOURCE_ROLE_ORG_MEMBER"
"RESOURCE_ROLE_ORG_RUNNERS_ADMIN"
"RESOURCE_ROLE_ORG_PROJECTS_ADMIN"
"RESOURCE_ROLE_ORG_AUTOMATIONS_ADMIN"
"RESOURCE_ROLE_ORG_GROUPS_ADMIN"
"RESOURCE_ROLE_ORG_AUDIT_LOG_READER"
"RESOURCE_ROLE_GROUP_ADMIN"
"RESOURCE_ROLE_GROUP_VIEWER"
"RESOURCE_ROLE_USER_IDENTITY"
"RESOURCE_ROLE_USER_VIEWER"
"RESOURCE_ROLE_USER_ADMIN"
"RESOURCE_ROLE_ENVIRONMENT_IDENTITY"
"RESOURCE_ROLE_ENVIRONMENT_ADMIN"
"RESOURCE_ROLE_ENVIRONMENT_USER"
"RESOURCE_ROLE_ENVIRONMENT_VIEWER"
"RESOURCE_ROLE_ENVIRONMENT_RUNNER"
"RESOURCE_ROLE_RUNNER_IDENTITY"
"RESOURCE_ROLE_RUNNER_ADMIN"
"RESOURCE_ROLE_RUNNER_LOCAL_ADMIN"
"RESOURCE_ROLE_RUNNER_MANAGED_ADMIN"
"RESOURCE_ROLE_RUNNER_USER"
"RESOURCE_ROLE_RUNNER_CONFIGURATION_READER"
"RESOURCE_ROLE_HOST_AUTHENTICATION_TOKEN_ADMIN"
"RESOURCE_ROLE_HOST_AUTHENTICATION_TOKEN_UPDATER"
"RESOURCE_ROLE_PROJECT_ADMIN"
"RESOURCE_ROLE_PROJECT_USER"
"RESOURCE_ROLE_PROJECT_EDITOR"
"RESOURCE_ROLE_ENVIRONMENT_SERVICE_ADMIN"
"RESOURCE_ROLE_ENVIRONMENT_SERVICE_VIEWER"
"RESOURCE_ROLE_ENVIRONMENT_SERVICE_USER"
"RESOURCE_ROLE_ENVIRONMENT_SERVICE_ENV"
"RESOURCE_ROLE_ENVIRONMENT_TASK_ADMIN"
"RESOURCE_ROLE_ENVIRONMENT_TASK_VIEWER"
"RESOURCE_ROLE_ENVIRONMENT_TASK_USER"
"RESOURCE_ROLE_ENVIRONMENT_TASK_ENV"
"RESOURCE_ROLE_SERVICE_ACCOUNT_IDENTITY"
"RESOURCE_ROLE_SERVICE_ACCOUNT_ADMIN"
"RESOURCE_ROLE_AGENT_EXECUTION_USER"
"RESOURCE_ROLE_AGENT_EXECUTION_ADMIN"
"RESOURCE_ROLE_AGENT_EXECUTION_RUNNER"
"RESOURCE_ROLE_AGENT_EXECUTION_OUTPUTS_REPORTER"
"RESOURCE_ROLE_AGENT_EXECUTION_VIEWER"
"RESOURCE_ROLE_AGENT_ADMIN"
"RESOURCE_ROLE_AGENT_VIEWER"
"RESOURCE_ROLE_AGENT_EXECUTOR"
"RESOURCE_ROLE_WORKFLOW_ADMIN"
"RESOURCE_ROLE_WORKFLOW_USER"
"RESOURCE_ROLE_WORKFLOW_VIEWER"
"RESOURCE_ROLE_WORKFLOW_EXECUTOR"
"RESOURCE_ROLE_SNAPSHOT_ADMIN"
"RESOURCE_ROLE_SNAPSHOT_RUNNER"
"RESOURCE_ROLE_WEBHOOK_ADMIN"
"RESOURCE_ROLE_WEBHOOK_VIEWER"
"RESOURCE_ROLE_WARMPOOL_RUNNER"
"RESOURCE_ROLE_WARMPOOL_ADMIN"
"RESOURCE_ROLE_WARMPOOL_VIEWER"
"RESOURCE_ROLE_SESSION_ADMIN"
"RESOURCE_ROLE_SESSION_USER"
"RESOURCE_ROLE_TEAM_ADMIN"
"RESOURCE_ROLE_TEAM_VIEWER"
groupId: optional string

Group identifier

formatuuid
organizationId: optional string

Organization identifier

formatuuid
resourceId: optional string

Resource identifier

formatuuid
resourceRole: optional ResourceRole

Role assigned to the group on this resource

One of the following:
"RESOURCE_ROLE_UNSPECIFIED"
"RESOURCE_ROLE_ORG_ADMIN"
"RESOURCE_ROLE_ORG_MEMBER"
"RESOURCE_ROLE_ORG_RUNNERS_ADMIN"
"RESOURCE_ROLE_ORG_PROJECTS_ADMIN"
"RESOURCE_ROLE_ORG_AUTOMATIONS_ADMIN"
"RESOURCE_ROLE_ORG_GROUPS_ADMIN"
"RESOURCE_ROLE_ORG_AUDIT_LOG_READER"
"RESOURCE_ROLE_GROUP_ADMIN"
"RESOURCE_ROLE_GROUP_VIEWER"
"RESOURCE_ROLE_USER_IDENTITY"
"RESOURCE_ROLE_USER_VIEWER"
"RESOURCE_ROLE_USER_ADMIN"
"RESOURCE_ROLE_ENVIRONMENT_IDENTITY"
"RESOURCE_ROLE_ENVIRONMENT_ADMIN"
"RESOURCE_ROLE_ENVIRONMENT_USER"
"RESOURCE_ROLE_ENVIRONMENT_VIEWER"
"RESOURCE_ROLE_ENVIRONMENT_RUNNER"
"RESOURCE_ROLE_RUNNER_IDENTITY"
"RESOURCE_ROLE_RUNNER_ADMIN"
"RESOURCE_ROLE_RUNNER_LOCAL_ADMIN"
"RESOURCE_ROLE_RUNNER_MANAGED_ADMIN"
"RESOURCE_ROLE_RUNNER_USER"
"RESOURCE_ROLE_RUNNER_CONFIGURATION_READER"
"RESOURCE_ROLE_HOST_AUTHENTICATION_TOKEN_ADMIN"
"RESOURCE_ROLE_HOST_AUTHENTICATION_TOKEN_UPDATER"
"RESOURCE_ROLE_PROJECT_ADMIN"
"RESOURCE_ROLE_PROJECT_USER"
"RESOURCE_ROLE_PROJECT_EDITOR"
"RESOURCE_ROLE_ENVIRONMENT_SERVICE_ADMIN"
"RESOURCE_ROLE_ENVIRONMENT_SERVICE_VIEWER"
"RESOURCE_ROLE_ENVIRONMENT_SERVICE_USER"
"RESOURCE_ROLE_ENVIRONMENT_SERVICE_ENV"
"RESOURCE_ROLE_ENVIRONMENT_TASK_ADMIN"
"RESOURCE_ROLE_ENVIRONMENT_TASK_VIEWER"
"RESOURCE_ROLE_ENVIRONMENT_TASK_USER"
"RESOURCE_ROLE_ENVIRONMENT_TASK_ENV"
"RESOURCE_ROLE_SERVICE_ACCOUNT_IDENTITY"
"RESOURCE_ROLE_SERVICE_ACCOUNT_ADMIN"
"RESOURCE_ROLE_AGENT_EXECUTION_USER"
"RESOURCE_ROLE_AGENT_EXECUTION_ADMIN"
"RESOURCE_ROLE_AGENT_EXECUTION_RUNNER"
"RESOURCE_ROLE_AGENT_EXECUTION_OUTPUTS_REPORTER"
"RESOURCE_ROLE_AGENT_EXECUTION_VIEWER"
"RESOURCE_ROLE_AGENT_ADMIN"
"RESOURCE_ROLE_AGENT_VIEWER"
"RESOURCE_ROLE_AGENT_EXECUTOR"
"RESOURCE_ROLE_WORKFLOW_ADMIN"
"RESOURCE_ROLE_WORKFLOW_USER"
"RESOURCE_ROLE_WORKFLOW_VIEWER"
"RESOURCE_ROLE_WORKFLOW_EXECUTOR"
"RESOURCE_ROLE_SNAPSHOT_ADMIN"
"RESOURCE_ROLE_SNAPSHOT_RUNNER"
"RESOURCE_ROLE_WEBHOOK_ADMIN"
"RESOURCE_ROLE_WEBHOOK_VIEWER"
"RESOURCE_ROLE_WARMPOOL_RUNNER"
"RESOURCE_ROLE_WARMPOOL_ADMIN"
"RESOURCE_ROLE_WARMPOOL_VIEWER"
"RESOURCE_ROLE_SESSION_ADMIN"
"RESOURCE_ROLE_SESSION_USER"
"RESOURCE_ROLE_TEAM_ADMIN"
"RESOURCE_ROLE_TEAM_VIEWER"
resourceType: optional ResourceType

Type of resource (runner, project, environment, etc.)

One of the following:
"RESOURCE_TYPE_UNSPECIFIED"
"RESOURCE_TYPE_ENVIRONMENT"
"RESOURCE_TYPE_RUNNER"
"RESOURCE_TYPE_PROJECT"
"RESOURCE_TYPE_TASK"
"RESOURCE_TYPE_TASK_EXECUTION"
"RESOURCE_TYPE_SERVICE"
"RESOURCE_TYPE_ORGANIZATION"
"RESOURCE_TYPE_USER"
"RESOURCE_TYPE_ENVIRONMENT_CLASS"
"RESOURCE_TYPE_RUNNER_SCM_INTEGRATION"
"RESOURCE_TYPE_HOST_AUTHENTICATION_TOKEN"
"RESOURCE_TYPE_GROUP"
"RESOURCE_TYPE_PERSONAL_ACCESS_TOKEN"
"RESOURCE_TYPE_USER_PREFERENCE"
"RESOURCE_TYPE_SERVICE_ACCOUNT"
"RESOURCE_TYPE_SECRET"
"RESOURCE_TYPE_SSO_CONFIG"
"RESOURCE_TYPE_DOMAIN_VERIFICATION"
"RESOURCE_TYPE_AGENT_EXECUTION"
"RESOURCE_TYPE_RUNNER_LLM_INTEGRATION"
"RESOURCE_TYPE_AGENT"
"RESOURCE_TYPE_ENVIRONMENT_SESSION"
"RESOURCE_TYPE_USER_SECRET"
"RESOURCE_TYPE_ORGANIZATION_POLICY"
"RESOURCE_TYPE_ORGANIZATION_SECRET"
"RESOURCE_TYPE_PROJECT_ENVIRONMENT_CLASS"
"RESOURCE_TYPE_BILLING"
"RESOURCE_TYPE_PROMPT"
"RESOURCE_TYPE_COUPON"
"RESOURCE_TYPE_COUPON_REDEMPTION"
"RESOURCE_TYPE_ACCOUNT"
"RESOURCE_TYPE_INTEGRATION"
"RESOURCE_TYPE_WORKFLOW"
"RESOURCE_TYPE_WORKFLOW_EXECUTION"
"RESOURCE_TYPE_WORKFLOW_EXECUTION_ACTION"
"RESOURCE_TYPE_SNAPSHOT"
"RESOURCE_TYPE_PREBUILD"
"RESOURCE_TYPE_ORGANIZATION_LLM_INTEGRATION"
"RESOURCE_TYPE_CUSTOM_DOMAIN"
"RESOURCE_TYPE_ROLE_ASSIGNMENT_CHANGED"
"RESOURCE_TYPE_GROUP_MEMBERSHIP_CHANGED"
"RESOURCE_TYPE_WEBHOOK"
"RESOURCE_TYPE_SCIM_CONFIGURATION"
"RESOURCE_TYPE_SERVICE_ACCOUNT_SECRET"
"RESOURCE_TYPE_ANNOUNCEMENT_BANNER"
"RESOURCE_TYPE_SERVICE_ACCOUNT_TOKEN"
"RESOURCE_TYPE_ROLE_ASSIGNMENT"
"RESOURCE_TYPE_WARM_POOL"
"RESOURCE_TYPE_NOTIFICATION"

ListRoleAssignments

curl https://app.gitpod.io/api/gitpod.v1.GroupService/ListRoleAssignments \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $GITPOD_API_KEY" \
    -d '{}'
{
  "assignments": [
    {
      "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "derivedFromOrgRole": "RESOURCE_ROLE_UNSPECIFIED",
      "groupId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "organizationId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "resourceId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "resourceRole": "RESOURCE_ROLE_UNSPECIFIED",
      "resourceType": "RESOURCE_TYPE_UNSPECIFIED"
    }
  ],
  "pagination": {
    "nextToken": "nextToken"
  }
}
Returns Examples
{
  "assignments": [
    {
      "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "derivedFromOrgRole": "RESOURCE_ROLE_UNSPECIFIED",
      "groupId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "organizationId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "resourceId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "resourceRole": "RESOURCE_ROLE_UNSPECIFIED",
      "resourceType": "RESOURCE_TYPE_UNSPECIFIED"
    }
  ],
  "pagination": {
    "nextToken": "nextToken"
  }
}