> ## Documentation Index
> Fetch the complete documentation index at: https://docs.honeyhive.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Set a member's roles in an organization

> Replace a member's roles in an organization with the roles given, and return the member. The
member's current sessions must reauthorize, so the new roles apply immediately. The member
may still be `INVITED`. The organization and the member are identified by the path
parameters alone. The `x-hh-org-id` header does not participate.

Each role must be one the organization's roles manifest defines for organizations, which are
the roles the HoneyHive app offers there. Any other role is refused with 400, including one
a manifest change removed, so writing back roles read before such a change can fail. When
the organization has no valid roles manifest in force, the roles cannot be checked and the
request is refused with 409.

When an API key makes the request, it cannot take the ability to revoke API keys from a
member who has signed in. If the member's roles grant `org.roles.get`, `org.roles.set`,
`org.fine_grained_api_key_cp.list` and `org.fine_grained_api_key_cp.delete`, and the new
roles would not, the request is refused with 409 and the change has to be made in the
HoneyHive app. An API key can still give any member those roles, and can change the roles of
a member who has not signed in yet.

Available on self-hosted deployments that do not enable an SSO group scheme. Elsewhere this
operation returns 404. An API key that carries a membership permission can carry no
permission other than the roles and membership permissions, and is created on an
organization.




## OpenAPI

````yaml https://raw.githubusercontent.com/honeyhiveai/honeyhive-openapi/main/control_plane_openapi.yaml patch /v1/orgs/{org_id}/members/{user_id}
openapi: 3.1.0
info:
  title: HoneyHive Control Plane API
  description: >
    Manage HoneyHive control-plane resources: organizations with their roles,
    templates and

    members, workspaces with their templates and members, projects with their
    members and

    alerts, and read org usage.


    Authentication requires a fine-grained control-plane API key (values

    start with `hh_fgcp_`), sent as `Authorization: Bearer <api-key>`.

    Project API keys used with the Data Plane API will not work here. Create

    a key in the HoneyHive app under an organization's or workspace's

    **Settings → API Keys**, or see

    [Authorization](https://docs.honeyhive.ai/v2/control-plane-sdk-reference/typescript#authorization)

    for details.
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  version: 1.19.0
servers:
  - url: https://api.cp.us.honeyhive.ai
security: []
tags:
  - name: Alerts
    description: >
      Define and manage alerts. Alerts evaluate event metrics on a schedule and
      trigger notifications when configured thresholds are crossed.
  - name: Org Members
    description: >
      List an organization's members, invite people to it, set a member's roles,
      and remove people from it and from everything in it. Available on
      self-hosted deployments that do not enable an SSO group scheme.
  - name: Org Templates
    description: >
      Read and replace an organization's templates manifest, which defines the
      metrics and charts that new projects start with. Each workspace gets its
      own copy when it is created, so a new version reaches an existing
      workspace's projects only where that workspace's manifest merges with the
      organization's.
  - name: Orgs
    description: >
      Read an organization's display name and the email domains whose users join
      it automatically when they sign in, and update its display name.
  - name: Project Members
    description: >
      List a project's members, invite people to it, set a member's roles, and
      remove people from it. Available on self-hosted deployments that do not
      enable an SSO group scheme.
  - name: Projects
    description: >
      Create and manage projects within a workspace. A project is the container
      for the events, datasets, evaluations, and alerts logged against it.
  - name: Roles
    description: >
      Read and replace an organization's roles manifest, which defines its roles
      and the permissions each one grants. Available on self-hosted deployments
      only.
  - name: Usage
    description: >
      Read an organization's usage: events and computed metrics per calendar
      month, and current user, workspace and project counts.
  - name: Virtual Dataplanes
    description: >
      Create and manage virtual data planes. A virtual data plane is a logical
      tenant boundary inside an organization, hosted on a physical cluster;
      several virtual data planes commonly share one cluster. Workspaces live
      inside a virtual data plane.
  - name: Workspace Members
    description: >
      List a workspace's members, invite people to it, set a member's roles, and
      remove people from it and from every project in it. Available on
      self-hosted deployments that do not enable an SSO group scheme.
  - name: Workspace Templates
    description: >
      Read and replace a workspace's templates manifest, which defines the
      metrics and charts that new projects in the workspace start with.
  - name: Workspaces
    description: >
      Read and manage workspaces. A workspace groups the projects belonging to
      one team or environment, and owns the API keys and AI provider secrets its
      projects share.
paths:
  /v1/orgs/{org_id}/members/{user_id}:
    patch:
      tags:
        - Org Members
      summary: Set a member's roles in an organization
      description: >
        Replace a member's roles in an organization with the roles given, and
        return the member. The

        member's current sessions must reauthorize, so the new roles apply
        immediately. The member

        may still be `INVITED`. The organization and the member are identified
        by the path

        parameters alone. The `x-hh-org-id` header does not participate.


        Each role must be one the organization's roles manifest defines for
        organizations, which are

        the roles the HoneyHive app offers there. Any other role is refused with
        400, including one

        a manifest change removed, so writing back roles read before such a
        change can fail. When

        the organization has no valid roles manifest in force, the roles cannot
        be checked and the

        request is refused with 409.


        When an API key makes the request, it cannot take the ability to revoke
        API keys from a

        member who has signed in. If the member's roles grant `org.roles.get`,
        `org.roles.set`,

        `org.fine_grained_api_key_cp.list` and
        `org.fine_grained_api_key_cp.delete`, and the new

        roles would not, the request is refused with 409 and the change has to
        be made in the

        HoneyHive app. An API key can still give any member those roles, and can
        change the roles of

        a member who has not signed in yet.


        Available on self-hosted deployments that do not enable an SSO group
        scheme. Elsewhere this

        operation returns 404. An API key that carries a membership permission
        can carry no

        permission other than the roles and membership permissions, and is
        created on an

        organization.
      operationId: updateOrgMember
      parameters:
        - in: path
          name: org_id
          required: true
          schema:
            type: string
          description: The unique identifier of the organization
        - in: path
          name: user_id
          required: true
          schema:
            type: string
          description: >-
            The member's user id, as the member list returns it. One person has
            the same user id in every organization, workspace and project
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchMemberRequest'
      responses:
        '200':
          description: Roles set
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PatchMemberResponse'
        '400':
          description: >-
            Invalid request body, or a role the organization's roles manifest
            does not define for organizations
        '404':
          description: >-
            Organization not found, the user is not a member of it, the caller
            may not set its members' roles, or the deployment does not offer
            member management. The response does not say which.
        '409':
          description: >-
            The organization has no valid roles manifest to check the roles
            against, or the request came from an API key and would take the
            ability to revoke API keys from a member who has signed in
      security:
        - ControlPlaneApiKey: []
components:
  schemas:
    PatchMemberRequest:
      type: object
      properties:
        role_names:
          type: array
          items:
            type: string
            minLength: 1
          minItems: 1
          description: >-
            The member's new roles at this scope, replacing the old ones. Each
            must be a role the organization's roles manifest defines for this
            scope's type, which are the roles the HoneyHive app offers for a
            member here. Any other role is refused with 400, including one a
            manifest change removed, so writing back roles read before a
            manifest change can fail
      required:
        - role_names
      additionalProperties: false
    PatchMemberResponse:
      type: object
      properties:
        success:
          type: boolean
          enum:
            - true
        data:
          $ref: '#/components/schemas/Member'
      required:
        - success
        - data
      additionalProperties: false
    Member:
      type: object
      properties:
        user_id:
          type: string
          description: The member's user id, the same at every scope
        email:
          type: string
          description: The member's email address
        name:
          type:
            - string
            - 'null'
          description: >-
            The member's display name from their identity provider, when it sent
            one
        role_names:
          type: array
          items:
            type: string
          description: The member's roles at this scope
        state:
          type: string
          enum:
            - INVITED
            - ONBOARDED
          description: >-
            `INVITED` until the member first signs in, `ONBOARDED` after. An API
            key cannot remove an `ONBOARDED` member whose organization roles let
            them revoke API keys, or change those roles to ones that do not, so
            an admin role a key grants can be undone with a key only while the
            member is `INVITED`.
        created_at:
          anyOf:
            - type: string
              format: date-time
            - type: string
          description: When the member was added to this scope
        updated_at:
          anyOf:
            - type: string
              format: date-time
            - type: string
            - type: 'null'
          description: When the member's membership of this scope last changed
      required:
        - user_id
        - email
        - name
        - role_names
        - state
        - created_at
        - updated_at
      additionalProperties: false
      description: One member of a scope
  securitySchemes:
    ControlPlaneApiKey:
      type: http
      scheme: bearer
      description: >-
        A fine-grained control-plane API key (values begin with `hh_fgcp_`).
        Project API keys used with the Data Plane API will not work here. Create
        one in the HoneyHive app under an organization's or workspace's
        **Settings → API Keys**.

````

## Related topics

- [Org Members](https://docs.honeyhive.ai/v2/cli-reference/ref/org-members.md)
- [Org Members Methods](https://docs.honeyhive.ai/v2/control-plane-sdk-reference/typescript/ref/org-members/index.md)
- [Set a member's roles in a workspace](https://docs.honeyhive.ai/v2/control-plane-api-reference-autogen/workspace-members/set-a-members-roles-in-a-workspace.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.