---
title: "Update Group Member Role"
method: PATCH
path: "/api/v1/groups/{group_id}/members/{user_id}"
tags: ["Team Management"]
---

# Update Group Member Role

`PATCH /api/v1/groups/{group_id}/members/{user_id}`

## Request

- Base URL: `https://api.athenahq.ai`
- URL: `https://api.athenahq.ai/api/v1/groups/{group_id}/members/{user_id}`
- Auth: API key in header `x-api-key`

Updates the role of a user who was explicitly added to a group (a `group_members` row, shown as `access_type: "group"` by `GET /api/v1/groups/{group_id}/members`). Accepts either the coarse `role` (admin/viewer) or a `role_id`: a system role or one of your organization's custom roles (see `GET /api/v1/roles`). Provide exactly one. Requires a global API key.

Organization members are out of scope: their access to every group in the org comes from their organization role, so a group-level write would not change what they can do. Targeting one returns `409`; use `PATCH /api/v1/organizations/members/{user_id}` instead. The API key's own user cannot be modified. There is no last-admin restriction at group scope: a group's only admin can be demoted, since organization admins retain admin access to every group in the organization.

**Roles other than `admin` and `viewer` are honored for access but are not yet rendered in the dashboard.** A `role_id` such as Editor or Billing Manager grants that role's real permissions on every website in the group, but the dashboard's group member list currently collapses any non-admin role to "Viewer". Prefer `admin` / `viewer` at group scope when a customer administrator also needs to see the assigned role.

## Request body

- UpdateGroupMemberRoleRequest: Request body for updating a group member's role. Provide exactly one of `role` or `role_id`.
  - `role` 'admin' | 'viewer': Coarse role to assign. Mutually exclusive with `role_id`.
  - `role_id` string: Assign any role by ID: a system role or one of your organization's custom roles (see `GET /api/v1/roles`). Mutually exclusive with `role`. Returns 404 if the role does not exist or belongs to another organization. System role IDs are GUID-shaped sentinels (e.g. `00000000-0000-0000-0000-000000000001`), not RFC 4122 UUIDs. At group scope, roles other than Admin and Viewer are honored for access but are displayed as "Viewer" in the dashboard's group member list.

## Response `200`

Member role updated successfully

- object
  - `success` boolean, required
  - `member` object, required
    - `user_id` string, uuid, required: Unique identifier of the user
    - `group_id` string, uuid, required: Unique identifier of the group
    - `role` string, required: Slug of the assigned role (e.g. 'admin', 'viewer', or a custom role's slug). Matches the `role` field returned by `GET /api/v1/groups/{group_id}/members`.
    - `role_id` string, required: ID of the assigned role (a system role ID or a custom role ID)

## Other responses

- `400`: Bad request - Invalid body or path parameters
- `401`: Unauthorized - Invalid or missing API key
- `403`: Forbidden - Not a global key, or self-modification
- `404`: Not found - Group does not exist in your organization, the user has no explicit group membership, or the requested `role_id` does not exist in your organization
- `409`: Conflict - The user's access to this group comes from their organization membership, so there is no group-level role to change. Changing their organization role instead applies across every group and website in the organization.
- `500`: Internal server error

## Changes

- **2026-11-03** `2d1d86d5e067`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/athenahq/apis/athenahq-api/changes/api/v1/groups/:group_id/members/:user_id/patch.md)

---

[API](https://skmtc.dev/athenahq/apis/athenahq-api.md) - [All operations](https://skmtc.dev/athenahq/apis/athenahq-api/llms.txt) - [OpenAPI document](https://skmtc.dev/athenahq/apis/athenahq-api/revisions/6cf9ca58edf6?raw)