<!-- llms.txt: https://workos.com/llms.txt -->

# GroupRoleAssignment

A group role assignment connects a [Group](https://workos.com/docs/reference/groups) to a [role](https://workos.com/docs/reference/roles). 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](https://workos.com/docs/reference/fga). When a resource is specified, members of the group receive the role's permissions on that resource and its descendants via [permission inheritance](https://workos.com/docs/fga/roles-and-permissions).

:::code-group{title="Example GroupRoleAssignment"}

```json language="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"
}
```

:::

## Assign a role to a group

Assign a role to a group on a specific resource.

:::code-group

```bash language="curl" title="Request" tab="1"
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
```

```rb language="ruby" title="Request" tab="1"
require "workos"

WorkOS.configure do |config|
  config.api_key = "sk_example_123456789"
end

WorkOS.client.authorization.create_group_role_assignment(
  group_id: "group_01HXYZ123456789ABCDEFGHIJ",
  role_slug: "admin"
)
```

```py language="python" title="Request" tab="1"
from workos import WorkOSClient

client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789")

client.authorization.create_group_role_assignment(
    group_id="group_01HXYZ123456789ABCDEFGHIJ", role_slug="admin"
)
```

```go language="go" title="Request" tab="1"
package main

import (
	"context"

	"github.com/workos/workos-go/v10"
)

func main() {
	client := workos.NewClient("sk_example_123456789")

	_, err := client.Authorization().CreateGroupRoleAssignment(context.Background(), "group_01HXYZ123456789ABCDEFGHIJ", &workos.AuthorizationCreateGroupRoleAssignmentParams{
		RoleSlug: "admin",
	})
	if err != nil {
		panic(err)
	}
}
```

```php language="php" title="Request" tab="1"
<?php

use WorkOS\WorkOS;

$workos = new WorkOS(
    apiKey: "sk_example_123456789",
    clientId: "client_123456789",
);

$workos
    ->authorization()
    ->createGroupRoleAssignment(
        groupId: "group_01HXYZ123456789ABCDEFGHIJ",
        roleSlug: "admin",
    );
```

```java language="java" title="Request" tab="1"
import com.workos.WorkOS;
import com.workos.authorization.AuthorizationApi.CreateGroupRoleAssignmentOptions;

WorkOS workos = new WorkOS("sk_example_123456789");

CreateGroupRoleAssignmentOptions options =
    CreateGroupRoleAssignmentOptions.builder().roleSlug("admin").build();

workos.authorization.createGroupRoleAssignment(
    "group_01HXYZ123456789ABCDEFGHIJ", options);
```

```cs language="dotnet" title="Request" tab="1"
using WorkOS;

var client = new WorkOSClient(new WorkOSOptions {
    ApiKey = "sk_example_123456789",
    ClientId = "client_123456789",
});

await client.Authorization.CreateGroupRoleAssignmentAsync("group_01HXYZ123456789ABCDEFGHIJ",
                                                          new AuthorizationCreateGroupRoleAssignmentOptions {
                                                              RoleSlug = "admin",
                                                          });
```

```rust language="rust" title="Request" tab="1"
use workos::Client;
use workos::authorization::CreateGroupRoleAssignmentParams;

#[tokio::main]
async fn main() -> Result<(), workos::Error> {
    let client = Client::builder()
        .api_key("sk_example_123456789")
        .client_id("client_123456789")
        .build();

    let _result = client
        .authorization()
        .create_group_role_assignment(
            "group_01HXYZ123456789ABCDEFGHIJ",
            CreateGroupRoleAssignmentParams {
                role_slug: "admin".into(),
                ..Default::default()
            }
        )
        .await?;

    Ok(())
}
```

```json language="json" title="Response" tab="2"
{
  "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"
}
```

:::

## Get a group role assignment

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

:::code-group

```bash language="curl" title="Request" tab="1"
curl "https://api.workos.com/authorization/groups/group_01HXYZ123456789ABCDEFGHIJ/role_assignments/gra_01HXYZ123456789ABCDEFGHIJ" \
  --header "Authorization: Bearer sk_example_123456789"
```

```rb language="ruby" title="Request" tab="1"
require "workos"

WorkOS.configure do |config|
  config.api_key = "sk_example_123456789"
end

WorkOS.client.authorization.get_group_role_assignment(
  group_id: "group_01HXYZ123456789ABCDEFGHIJ",
  role_assignment_id: "gra_01HXYZ123456789ABCDEFGHIJ"
)
```

```py language="python" title="Request" tab="1"
from workos import WorkOSClient

client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789")

client.authorization.get_group_role_assignment(
    group_id="group_01HXYZ123456789ABCDEFGHIJ",
    role_assignment_id="gra_01HXYZ123456789ABCDEFGHIJ",
)
```

```go language="go" title="Request" tab="1"
package main

import (
	"context"

	"github.com/workos/workos-go/v10"
)

func main() {
	client := workos.NewClient("sk_example_123456789")

	_, err := client.Authorization().GetGroupRoleAssignment(context.Background(), "group_01HXYZ123456789ABCDEFGHIJ", "gra_01HXYZ123456789ABCDEFGHIJ")
	if err != nil {
		panic(err)
	}
}
```

```php language="php" title="Request" tab="1"
<?php

use WorkOS\WorkOS;

$workos = new WorkOS(
    apiKey: "sk_example_123456789",
    clientId: "client_123456789",
);

$workos
    ->authorization()
    ->getGroupRoleAssignment(
        groupId: "group_01HXYZ123456789ABCDEFGHIJ",
        roleAssignmentId: "gra_01HXYZ123456789ABCDEFGHIJ",
    );
```

```java language="java" title="Request" tab="1"
import com.workos.WorkOS;

WorkOS workos = new WorkOS("sk_example_123456789");

workos.authorization.getGroupRoleAssignment(
    "group_01HXYZ123456789ABCDEFGHIJ", "gra_01HXYZ123456789ABCDEFGHIJ");
```

```cs language="dotnet" title="Request" tab="1"
using WorkOS;

var client = new WorkOSClient(new WorkOSOptions {
    ApiKey = "sk_example_123456789",
    ClientId = "client_123456789",
});

await client.Authorization.GetGroupRoleAssignmentAsync("group_01HXYZ123456789ABCDEFGHIJ",
                                                       "gra_01HXYZ123456789ABCDEFGHIJ");
```

```rust language="rust" title="Request" tab="1"
use workos::Client;

#[tokio::main]
async fn main() -> Result<(), workos::Error> {
    let client = Client::builder()
        .api_key("sk_example_123456789")
        .client_id("client_123456789")
        .build();

    let _result = client
        .authorization()
        .get_group_role_assignment(
            "group_01HXYZ123456789ABCDEFGHIJ",
            "gra_01HXYZ123456789ABCDEFGHIJ"
        )
        .await?;

    Ok(())
}
```

```json language="json" title="Response" tab="2"
{
  "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"
}
```

:::

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

:::code-group

```bash language="curl" title="Request" tab="1"
curl "https://api.workos.com/authorization/groups/group_01HXYZ123456789ABCDEFGHIJ/role_assignments" \
  --header "Authorization: Bearer sk_example_123456789"
```

```rb language="ruby" title="Request" tab="1"
require "workos"

WorkOS.configure do |config|
  config.api_key = "sk_example_123456789"
end

WorkOS.client.authorization.list_group_role_assignments(group_id: "group_01HXYZ123456789ABCDEFGHIJ")
```

```py language="python" title="Request" tab="1"
from workos import WorkOSClient

client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789")

client.authorization.list_group_role_assignments(
    group_id="group_01HXYZ123456789ABCDEFGHIJ"
)
```

```go language="go" title="Request" tab="1"
package main

import (
	"context"

	"github.com/workos/workos-go/v10"
)

func main() {
	client := workos.NewClient("sk_example_123456789")

	_, err := client.Authorization().ListGroupRoleAssignments(context.Background(), "group_01HXYZ123456789ABCDEFGHIJ")
	if err != nil {
		panic(err)
	}
}
```

```php language="php" title="Request" tab="1"
<?php

use WorkOS\WorkOS;

$workos = new WorkOS(
    apiKey: "sk_example_123456789",
    clientId: "client_123456789",
);

$workos
    ->authorization()
    ->listGroupRoleAssignments(groupId: "group_01HXYZ123456789ABCDEFGHIJ");
```

```java language="java" title="Request" tab="1"
import com.workos.WorkOS;

WorkOS workos = new WorkOS("sk_example_123456789");

workos.authorization.listGroupRoleAssignments("group_01HXYZ123456789ABCDEFGHIJ");
```

```cs language="dotnet" title="Request" tab="1"
using WorkOS;

var client = new WorkOSClient(new WorkOSOptions {
    ApiKey = "sk_example_123456789",
    ClientId = "client_123456789",
});

await client.Authorization.ListGroupRoleAssignmentsAsync("group_01HXYZ123456789ABCDEFGHIJ");
```

```rust language="rust" title="Request" tab="1"
use workos::Client;

#[tokio::main]
async fn main() -> Result<(), workos::Error> {
    let client = Client::builder()
        .api_key("sk_example_123456789")
        .client_id("client_123456789")
        .build();

    let _result = client
        .authorization()
        .list_group_role_assignments("group_01HXYZ123456789ABCDEFGHIJ")
        .await?;

    Ok(())
}
```

```json language="json" title="Response" tab="2"
{
  "object": "list",
  "data": [
    {
      "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"
    }
  ],
  "list_metadata": {
    "before": "gra_01HXYZ123456789ABCDEFGHIJ",
    "after": "gra_01HXYZ987654321KJIHGFEDCBA"
  }
}
```

:::

## Remove a group role assignment

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

:::code-group

```bash language="curl" title="Request" tab="1"
curl --request DELETE \
  --url "https://api.workos.com/authorization/groups/group_01HXYZ123456789ABCDEFGHIJ/role_assignments/gra_01HXYZ123456789ABCDEFGHIJ" \
  --header "Authorization: Bearer sk_example_123456789"
```

```rb language="ruby" title="Request" tab="1"
require "workos"

WorkOS.configure do |config|
  config.api_key = "sk_example_123456789"
end

WorkOS.client.authorization.delete_group_role_assignment(
  group_id: "group_01HXYZ123456789ABCDEFGHIJ",
  role_assignment_id: "gra_01HXYZ123456789ABCDEFGHIJ"
)
```

```py language="python" title="Request" tab="1"
from workos import WorkOSClient

client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789")

client.authorization.delete_group_role_assignment(
    group_id="group_01HXYZ123456789ABCDEFGHIJ",
    role_assignment_id="gra_01HXYZ123456789ABCDEFGHIJ",
)
```

```go language="go" title="Request" tab="1"
package main

import (
	"context"

	"github.com/workos/workos-go/v10"
)

func main() {
	client := workos.NewClient("sk_example_123456789")

	_, err := client.Authorization().DeleteGroupRoleAssignment(context.Background(), "group_01HXYZ123456789ABCDEFGHIJ", "gra_01HXYZ123456789ABCDEFGHIJ")
	if err != nil {
		panic(err)
	}
}
```

```php language="php" title="Request" tab="1"
<?php

use WorkOS\WorkOS;

$workos = new WorkOS(
    apiKey: "sk_example_123456789",
    clientId: "client_123456789",
);

$workos
    ->authorization()
    ->deleteGroupRoleAssignment(
        groupId: "group_01HXYZ123456789ABCDEFGHIJ",
        roleAssignmentId: "gra_01HXYZ123456789ABCDEFGHIJ",
    );
```

```java language="java" title="Request" tab="1"
import com.workos.WorkOS;

WorkOS workos = new WorkOS("sk_example_123456789");

workos.authorization.deleteGroupRoleAssignment(
    "group_01HXYZ123456789ABCDEFGHIJ", "gra_01HXYZ123456789ABCDEFGHIJ");
```

```cs language="dotnet" title="Request" tab="1"
using WorkOS;

var client = new WorkOSClient(new WorkOSOptions {
    ApiKey = "sk_example_123456789",
    ClientId = "client_123456789",
});

await client.Authorization.DeleteGroupRoleAssignmentAsync("group_01HXYZ123456789ABCDEFGHIJ",
                                                          "gra_01HXYZ123456789ABCDEFGHIJ");
```

```rust language="rust" title="Request" tab="1"
use workos::Client;

#[tokio::main]
async fn main() -> Result<(), workos::Error> {
    let client = Client::builder()
        .api_key("sk_example_123456789")
        .client_id("client_123456789")
        .build();

    let _result = client
        .authorization()
        .delete_group_role_assignment(
            "group_01HXYZ123456789ABCDEFGHIJ",
            "gra_01HXYZ123456789ABCDEFGHIJ"
        )
        .await?;

    Ok(())
}
```

:::

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

:::code-group

```bash language="curl" title="Request" tab="1"
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
```

```rb language="ruby" title="Request" tab="1"
require "workos"

WorkOS.configure do |config|
  config.api_key = "sk_example_123456789"
end

WorkOS.client.authorization.delete_group_role_assignments(
  group_id: "group_01HXYZ123456789ABCDEFGHIJ",
  role_slug: "admin"
)
```

```py language="python" title="Request" tab="1"
from workos import WorkOSClient

client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789")

client.authorization.delete_group_role_assignments(
    group_id="group_01HXYZ123456789ABCDEFGHIJ", role_slug="admin"
)
```

```go language="go" title="Request" tab="1"
package main

import (
	"context"

	"github.com/workos/workos-go/v10"
)

func main() {
	client := workos.NewClient("sk_example_123456789")

	_, err := client.Authorization().DeleteGroupRoleAssignments(context.Background(), "group_01HXYZ123456789ABCDEFGHIJ", &workos.AuthorizationDeleteGroupRoleAssignmentsParams{
		RoleSlug: "admin",
	})
	if err != nil {
		panic(err)
	}
}
```

```php language="php" title="Request" tab="1"
<?php

use WorkOS\WorkOS;

$workos = new WorkOS(
    apiKey: "sk_example_123456789",
    clientId: "client_123456789",
);

$workos
    ->authorization()
    ->deleteGroupRoleAssignments(
        groupId: "group_01HXYZ123456789ABCDEFGHIJ",
        roleSlug: "admin",
    );
```

```java language="java" title="Request" tab="1"
import com.workos.WorkOS;
import com.workos.authorization.AuthorizationApi.DeleteGroupRoleAssignmentsOptions;

WorkOS workos = new WorkOS("sk_example_123456789");

DeleteGroupRoleAssignmentsOptions options =
    DeleteGroupRoleAssignmentsOptions.builder().roleSlug("admin").build();

workos.authorization.deleteGroupRoleAssignments(
    "group_01HXYZ123456789ABCDEFGHIJ", options);
```

```cs language="dotnet" title="Request" tab="1"
using WorkOS;

var client = new WorkOSClient(new WorkOSOptions {
    ApiKey = "sk_example_123456789",
    ClientId = "client_123456789",
});

await client.Authorization.DeleteGroupRoleAssignmentsAsync("group_01HXYZ123456789ABCDEFGHIJ",
                                                           new AuthorizationDeleteGroupRoleAssignmentsOptions {
                                                               RoleSlug = "admin",
                                                           });
```

```rust language="rust" title="Request" tab="1"
use workos::Client;
use workos::authorization::DeleteGroupRoleAssignmentsParams;

#[tokio::main]
async fn main() -> Result<(), workos::Error> {
    let client = Client::builder()
        .api_key("sk_example_123456789")
        .client_id("client_123456789")
        .build();

    let _result = client
        .authorization()
        .delete_group_role_assignments(
            "group_01HXYZ123456789ABCDEFGHIJ",
            DeleteGroupRoleAssignmentsParams {
                role_slug: "admin".into(),
                ..Default::default()
            }
        )
        .await?;

    Ok(())
}
```

:::

## Replace all role assignments for a group

Replace all role assignments for a group with the provided list. Existing assignments not in the list will be removed.

:::code-group

```bash language="curl" title="Request" tab="1"
curl --request PUT \
  --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_assignments": [
            {
                "role_slug": "admin",
                "resource_id": "authz_resource_01HXYZ123456789ABCDEFGH",
                "resource_external_id": "proj-456",
                "resource_type_slug": "project"
            }
        ]
    }
BODY
```

```rb language="ruby" title="Request" tab="1"
require "workos"

WorkOS.configure do |config|
  config.api_key = "sk_example_123456789"
end

WorkOS.client.authorization.update_group_role_assignments(
  group_id: "group_01HXYZ123456789ABCDEFGHIJ",
  role_assignments: [
    {
      role_slug: "admin",
      resource_id: "authz_resource_01HXYZ123456789ABCDEFGH",
      resource_external_id: "proj-456",
      resource_type_slug: "project"
    }
  ]
)
```

```py language="python" title="Request" tab="1"
from workos import WorkOSClient

client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789")

client.authorization.update_group_role_assignments(
    group_id="group_01HXYZ123456789ABCDEFGHIJ",
    role_assignments=[
        {
            "role_slug": "admin",
            "resource_id": "authz_resource_01HXYZ123456789ABCDEFGH",
            "resource_external_id": "proj-456",
            "resource_type_slug": "project",
        }
    ],
)
```

```go language="go" title="Request" tab="1"
package main

import (
	"context"

	"github.com/workos/workos-go/v10"
)

func main() {
	client := workos.NewClient("sk_example_123456789")

	_, err := client.Authorization().UpdateGroupRoleAssignments(context.Background(), "group_01HXYZ123456789ABCDEFGHIJ", &workos.AuthorizationUpdateGroupRoleAssignmentsParams{
		RoleAssignments: []any{
			map[string]any{
				"role_slug":            "admin",
				"resource_id":          "authz_resource_01HXYZ123456789ABCDEFGH",
				"resource_external_id": "proj-456",
				"resource_type_slug":   "project",
			},
		},
	})
	if err != nil {
		panic(err)
	}
}
```

```php language="php" title="Request" tab="1"
<?php

use WorkOS\WorkOS;

$workos = new WorkOS(
    apiKey: "sk_example_123456789",
    clientId: "client_123456789",
);

$workos->authorization()->updateGroupRoleAssignments(
    groupId: "group_01HXYZ123456789ABCDEFGHIJ",
    roleAssignments: [
        [
            "role_slug" => "admin",
            "resource_id" => "authz_resource_01HXYZ123456789ABCDEFGH",
            "resource_external_id" => "proj-456",
            "resource_type_slug" => "project",
        ],
    ],
);
```

```java language="java" title="Request" tab="1"
import com.workos.WorkOS;
import com.workos.authorization.AuthorizationApi.UpdateGroupRoleAssignmentsOptions;

WorkOS workos = new WorkOS("sk_example_123456789");

UpdateGroupRoleAssignmentsOptions options =
    UpdateGroupRoleAssignmentsOptions.builder()
        .roleAssignments(List.of(Map.of("role_slug",
            "admin",
            "resource_id",
            "authz_resource_01HXYZ123456789ABCDEFGH",
            "resource_external_id",
            "proj-456",
            "resource_type_slug",
            "project")))
        .build();

workos.authorization.updateGroupRoleAssignments(
    "group_01HXYZ123456789ABCDEFGHIJ", options);
```

```cs language="dotnet" title="Request" tab="1"
using WorkOS;

var client = new WorkOSClient(new WorkOSOptions {
    ApiKey = "sk_example_123456789",
    ClientId = "client_123456789",
});

await client.Authorization.UpdateGroupRoleAssignmentsAsync(
    "group_01HXYZ123456789ABCDEFGHIJ", new AuthorizationUpdateGroupRoleAssignmentsOptions {
        RoleAssignments =
            new[] {
                new Dictionary<string, object> {
                    { "role_slug", "admin" },
                    { "resource_id", "authz_resource_01HXYZ123456789ABCDEFGH" },
                    { "resource_external_id", "proj-456" },
                    { "resource_type_slug", "project" },
                },
            },
    });
```

```rust language="rust" title="Request" tab="1"
use workos::Client;
use workos::authorization::UpdateGroupRoleAssignmentsParams;

#[tokio::main]
async fn main() -> Result<(), workos::Error> {
    let client = Client::builder()
        .api_key("sk_example_123456789")
        .client_id("client_123456789")
        .build();

    let _result = client
        .authorization()
        .update_group_role_assignments(
            "group_01HXYZ123456789ABCDEFGHIJ",
            UpdateGroupRoleAssignmentsParams {
                role_assignments: vec![
                    serde_json::json!({
                        "role_slug": "admin",
                        "resource_id": "authz_resource_01HXYZ123456789ABCDEFGH",
                        "resource_external_id": "proj-456",
                        "resource_type_slug": "project",
                    }),
                ],
                ..Default::default()
            }
        )
        .await?;

    Ok(())
}
```

```json language="json" title="Response" tab="2"
{
  "object": "list",
  "data": [
    {
      "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"
    }
  ],
  "list_metadata": {
    "before": "gra_01HXYZ123456789ABCDEFGHIJ",
    "after": "gra_01HXYZ987654321KJIHGFEDCBA"
  }
}
```

:::

### group_role_assignment

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | "group_role_assignment" | Yes | Distinguishes the group role assignment object. |
| `id` | string | Yes | Unique identifier of the group role assignment. |
| `group_id` | string | Yes | The ID of the group the role is assigned to. |
| `role` | object | Yes | The role included in the assignment. |
| `resource` | object | Yes | The resource the role is assigned on. |
| `created_at` | string | Yes | An ISO 8601 timestamp. |
| `updated_at` | string | Yes | An ISO 8601 timestamp. |

### POST /authorization/groups/{group_id}/role_assignments

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `role_slug` | string | Yes | The slug of the role to assign to the group. |
| `resource_id` | string | No | The ID of the resource. Omit along with the external-id fields to target the organization itself. |
| `resource_external_id` | string | No | The external ID of the resource. |
| `resource_type_slug` | string | No | The resource type slug. |

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `group_id` | string | Yes | The ID of the group. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `group_role_assignment` | object | Distinguishes the group role assignment object. |

### GET /authorization/groups/{group_id}/role_assignments/{role_assignment_id}

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `group_id` | string | Yes | The ID of the group. |
| `role_assignment_id` | string | Yes | The ID of the group role assignment. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `group_role_assignment` | object | Distinguishes the group role assignment object. |

### GET /authorization/groups/{group_id}/role_assignments

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `group_id` | string | Yes | The ID of the group. |
| `before` | string | No | An object ID that defines your place in the list. When the ID is not present, you are at the end of the list. For example, if you make a list request and receive 100 objects, ending with `"obj_123"`, your subsequent call can include `before="obj_123"` to fetch a new batch of objects before `"obj_123"`. |
| `after` | string | No | An object ID that defines your place in the list. When the ID is not present, you are at the end of the list. For example, if you make a list request and receive 100 objects, ending with `"obj_123"`, your subsequent call can include `after="obj_123"` to fetch a new batch of objects after `"obj_123"`. |
| `limit` | integer | No | Upper limit on the number of objects to return, between `1` and `100`. Defaults to `10`. |
| `order` | "normal" \| "desc" \| "asc" | No | Order the results by the creation time. Supported values are `"asc"` (ascending), `"desc"` (descending), and `"normal"` (descending with reversed cursor semantics where `before` fetches older records and `after` fetches newer records). Defaults to `normal`. |

### DELETE /authorization/groups/{group_id}/role_assignments/{role_assignment_id}

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `group_id` | string | Yes | The ID of the group. |
| `role_assignment_id` | string | Yes | The ID of the group role assignment to remove. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `empty` | empty | Returns an empty response on success. |

### DELETE /authorization/groups/{group_id}/role_assignments

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `role_slug` | string | Yes | The slug of the role to remove assignments for. |
| `resource_id` | string | No | The ID of the resource. Mutually exclusive with `resource_external_id` and `resource_type_slug`. |
| `resource_external_id` | string | No | The external ID of the resource. |
| `resource_type_slug` | string | No | The resource type slug. |

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `group_id` | string | Yes | The ID of the group. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `empty` | empty | Returns an empty response on success. |

### PUT /authorization/groups/{group_id}/role_assignments

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `role_assignments` | object[] | Yes | The list of role assignments that should exist for the group. All existing assignments will be replaced. |

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `group_id` | string | Yes | The ID of the group. |