---
title: "Assign role to group"
method: POST
path: "/zones/{zoneId}/groups/{groupId}/roles"
tags: ["Groups"]
---

# Assign role to group

`POST /zones/{zoneId}/groups/{groupId}/roles`

Assigns a role to the group; members inherit it. Provide role_id, or role_identifier with owner_type. Returns the shared role-assignment shape with `principal_type` set to `group`.

## Path parameters

- `zoneId` string, required
- `groupId` string, required

## Request body

- IamRoleAssignmentCreate — Schema for assigning a role to a principal. Provide exactly one of role_id or role_identifier. When role_identifier is used, owner_type is required to disambiguate roles that share an identifier across owner types; owner_type must be omitted when role_id is used.
  - `role_id` string — ID of the role to assign. Provide exactly one of role_id or role_identifier; owner_type must be omitted when role_id is used.
  - `role_identifier` string — Role identifier: a lowercase slug (letters and digits separated by single hyphens or underscores), unique per owner type within a zone. Role identifiers surface in policy evaluation, so the slug restriction keeps them unambiguous in policy text.
  - `owner_type` 'platform' | 'customer' — Owner type of the role to assign. Required with role_identifier (an identifier is unique only per owner type); must be omitted with role_id.
  - `scope_type` string — The kind of resource to scope the grant to (e.g. `zone`). Provide together with scope_id, or omit both for an unscoped assignment (applies to the owning zone itself). Only platform roles on the org zone may carry a scope.
  - `scope_id` string — The ID of the resource to scope the grant to. Provide together with scope_type, or omit both for an unscoped assignment. When scope_type is `zone`, this must reference a different zone in the same organization.

## Response `201`

Represents a role assigned to a principal within a zone

- IamRoleAssignment — Represents a role assigned to a principal within a zone
  - `id` string, required — Unique identifier of the role assignment
  - `zone_id` string, required — Zone this assignment belongs to
  - `principal_type` string, required — The kind of principal the role is assigned to: `user`, `application`, or `group`. A role assigned to a `group` is inherited by that group's members.
  - `principal_id` string, required — ID of the principal the role is assigned to (a user, application, or group ID).
  - `role_id` string, required — ID of the assigned role
  - `role_identifier` string, required — Role identifier: a lowercase slug (letters and digits separated by single hyphens or underscores), unique per owner type within a zone. Role identifiers surface in policy evaluation, so the slug restriction keeps them unambiguous in policy text.
  - `role_owner_type` 'platform' | 'customer', required — Owner type of the assigned role. Disambiguates roles that share an identifier across owner types.
  - `scope_type` string, nullable — The kind of resource this grant is scoped to (e.g. `zone`). Null when the assignment is unscoped (applies to the owning zone itself).
  - `scope_id` string, nullable — The ID of the scoped resource. Null when the assignment is unscoped.
  - `created_at` string, date-time, required — Entity creation timestamp
  - `updated_at` string, date-time, required — Entity update timestamp

## Other responses

- `400` — Error response
- `404` — Error response
- `default` — Error response

## Changes

- **2026-08-26** `d65d51379d93` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/keycardai/apis/untitled-api/changes/zones/:zoneId/groups/:groupId/roles/post.md)

---

[API](https://skmtc.dev/keycardai/apis/untitled-api.md) · [All operations](https://skmtc.dev/keycardai/apis/untitled-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/keycardai/untitled-api/revisions/d65d51379d93/schema)