> ## Documentation Index > Fetch the complete documentation index at: https://docs.athenahq.ai/llms.txt > Use this file to discover all available pages before exploring further. # Update Group Member Role > 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. ## OpenAPI ````yaml /api-reference/openapi.json patch /api/v1/groups/{group_id}/members/{user_id} openapi: 3.1.0 info: title: AthenaHQ API description: >- AthenaHQ API provides programmatic access to manage your websites and prompts for AI-powered content optimization. version: 1.0.0 contact: email: support@athenahq.ai servers: - url: https://api.athenahq.ai description: Production server security: - apiKey: [] tags: - name: Basics description: Core API operations for managing websites and prompts - name: Metrics description: Metrics and analytics endpoints for tracking AI visibility - name: Billing description: Billing and credits endpoints for managing usage - name: Team Management description: Endpoints for managing team members and invitations - name: Groups description: Endpoints for managing groups of websites - name: Content description: >- Endpoints for accessing Content Hub data — tabs, tracked URLs, and per-URL prompt breakdowns. - name: Pitch Workspace description: >- Endpoints for accessing pitch workspace reports — org-scoped pitch runs with competitors, prompts, attributes, and aggregate metrics. - name: Knowledge Base description: >- Endpoints for reading the brand Knowledge Base — approved brand facts and the pillars that organize them. paths: /api/v1/groups/{group_id}/members/{user_id}: parameters: - name: group_id in: path required: true schema: type: string format: uuid description: The unique identifier of the group - name: user_id in: path required: true schema: type: string format: uuid description: The unique identifier of the target user patch: tags: - Team Management summary: Update Group Member Role description: >- 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. operationId: updateGroupMemberRole requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateGroupMemberRoleRequest' responses: '200': description: Member role updated successfully content: application/json: schema: type: object properties: success: type: boolean example: true member: type: object required: - user_id - group_id - role - role_id properties: user_id: type: string format: uuid description: Unique identifier of the user group_id: type: string format: uuid description: Unique identifier of the group role: type: string description: >- 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`. example: viewer role_id: type: string pattern: >- ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ description: >- ID of the assigned role (a system role ID or a custom role ID) required: - success - member '400': description: Bad request - Invalid body or path parameters content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized - Invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Forbidden - Not a global key, or self-modification content: application/json: schema: $ref: '#/components/schemas/Error' examples: not_global: value: error: 'Forbidden: global API key required' self_modification: value: error: You cannot modify your own membership '404': description: >- 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 content: application/json: schema: $ref: '#/components/schemas/Error' examples: group_not_found: value: error: Group not found member_not_found: value: error: Group member not found role_not_found: value: error: Role not found '409': description: >- 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. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: >- User is an organization member: their access to this group comes from their organization role, so there is no group-level role to change. Changing it with PATCH /api/v1/organizations/members/{user_id} would apply across every group and website in the organization, not only this group. '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' security: - apiKey: [] components: schemas: UpdateGroupMemberRoleRequest: type: object description: >- Request body for updating a group member's role. Provide exactly one of `role` or `role_id`. properties: role: type: string enum: - admin - viewer description: Coarse role to assign. Mutually exclusive with `role_id`. example: viewer role_id: type: string pattern: >- ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ description: >- 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. example: 789e0123-e89b-12d3-a456-426614174000 Error: type: object description: Error response object required: - error properties: error: type: string description: Error message describing what went wrong example: Unauthorized securitySchemes: apiKey: type: apiKey in: header name: x-api-key description: >- API key for authentication. You can create one [here](https://app.athenahq.ai/organization?tab=api). ````