GroupRoleAssignment

A group role assignment connects a Group to a role. When a role is assigned to a group, all members of that group gain the permissions included in that role. As organization memberships are added to or removed from the group, the role and its permissions automatically propagate to the current members.

Group role assignments can also be scoped to a specific resource for Fine-Grained Authorization. When a resource is specified, members of the group receive the role’s permissions on that resource and its descendants via permission inheritance.

Example GroupRoleAssignment

cURL

 {
  "object": "group_role_assignment",
  "id": "gra_01HXYZ123456789ABCDEFGH",
  "group_id": "group_01HXYZ123456789ABCDEFGHIJ",
  "role": {
    "slug": "admin"
  },
  "resource": {
    "id": "authz_resource_01HXYZ123456789ABCDEFGH",
    "external_id": "proj-456",
    "resource_type_slug": "project"
  },
  "created_at": "2026-01-15T12:00:00.000Z",
  "updated_at": "2026-01-15T12:00:00.000Z"
}

`group_role_assignment`

List role assignments for a group

List all role assignments granted to a group. Each assignment represents a role granted to the group on a resource.

cURL

 curl "https://api.workos.com/authorization/groups/group_01HXYZ123456789ABCDEFGHIJ/role_assignments" \
  --header "Authorization: Bearer sk_example_123456789"

Feature flagged

GET

`/authorization/groups/:group_id/role_assignments`

`Parameters`

`Returns` `object`

Assign a role to a group

Assign a role to a group on a specific resource.

cURL

 curl --request POST \
  --url "https://api.workos.com/authorization/groups/group_01HXYZ123456789ABCDEFGHIJ/role_assignments" \
  --header "Authorization: Bearer sk_example_123456789" \
  --header "Content-Type: application/json" \
  -d @- <<'BODY'
    {
        "role_slug": "admin"
    }
BODY

Feature flagged

POST

`/authorization/groups/:group_id/role_assignments`

`Parameters`

`Returns`

Get a group role assignment

Get a specific role assignment for a group by its ID.

cURL

 curl "https://api.workos.com/authorization/groups/group_01HXYZ123456789ABCDEFGHIJ/role_assignments/gra_01HXYZ123456789ABCDEFGHIJ" \
  --header "Authorization: Bearer sk_example_123456789"

Feature flagged

GET

`/authorization/groups/:group_id/role_assignments/:role_assignment_id`

`Parameters`

`Returns`

Remove a group role assignment

Remove a specific role assignment from a group by its ID.

cURL

 curl --request DELETE \
  --url "https://api.workos.com/authorization/groups/group_01HXYZ123456789ABCDEFGHIJ/role_assignments/gra_01HXYZ123456789ABCDEFGHIJ" \
  --header "Authorization: Bearer sk_example_123456789"

Feature flagged

DELETE

`/authorization/groups/:group_id/role_assignments/:role_assignment_id`

`Parameters`

`Returns`

Remove group role assignments by criteria

Remove role assignments from a group that match the provided criteria. Returns 404 when no matching active assignment is found.

cURL

 curl --request DELETE \
  --url "https://api.workos.com/authorization/groups/group_01HXYZ123456789ABCDEFGHIJ/role_assignments" \
  --header "Authorization: Bearer sk_example_123456789" \
  --header "Content-Type: application/json" \
  -d @- <<'BODY'
    {
        "role_slug": "admin"
    }
BODY

Feature flagged

DELETE

`/authorization/groups/:group_id/role_assignments`

`Parameters`

`Returns`

Magic LinkContinue to the next section