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

# Replace an organization's roles manifest

> Save a new version of an organization's roles manifest, which becomes the latest version.
Every member's current session must reauthorize, so the new roles apply to everyone
immediately. The organization is identified by the `org_id` path parameter alone. The
`x-hh-org-id` header does not participate.

When an API key makes the request, two further rules apply:

- If the organization's current roles manifest already has this content, nothing is saved
  and that version is returned, so applying the same manifest repeatedly is safe.
- A manifest that would leave no onboarded, active member holding `org.roles.get`,
  `org.roles.set`, `org.fine_grained_api_key_cp.list` and
  `org.fine_grained_api_key_cp.delete` is refused with 409, so someone in the organization
  can always revoke the key.

Available on self-hosted deployments only. Elsewhere this operation returns 404. An API key
that carries `org.roles.get` or `org.roles.set` 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 put /v1/orgs/{org_id}/roles_manifest
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}/roles_manifest:
    put:
      tags:
        - Roles
      summary: Replace an organization's roles manifest
      description: >
        Save a new version of an organization's roles manifest, which becomes
        the latest version.

        Every member's current session must reauthorize, so the new roles apply
        to everyone

        immediately. The organization is identified by the `org_id` path
        parameter alone. The

        `x-hh-org-id` header does not participate.


        When an API key makes the request, two further rules apply:


        - If the organization's current roles manifest already has this content,
        nothing is saved
          and that version is returned, so applying the same manifest repeatedly is safe.
        - A manifest that would leave no onboarded, active member holding
        `org.roles.get`,
          `org.roles.set`, `org.fine_grained_api_key_cp.list` and
          `org.fine_grained_api_key_cp.delete` is refused with 409, so someone in the organization
          can always revoke the key.

        Available on self-hosted deployments only. Elsewhere this operation
        returns 404. An API key

        that carries `org.roles.get` or `org.roles.set` can carry no permission
        other than the

        roles and membership permissions, and is created on an organization.
      operationId: updateRolesManifest
      parameters:
        - in: path
          name: org_id
          required: true
          schema:
            type: string
          description: The unique identifier of the organization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PutRolesManifestRequest'
      responses:
        '200':
          description: >-
            Roles manifest saved, or returned unchanged for an API key whose
            content matched
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateRolesManifestResponse'
        '400':
          description: Invalid request body, or YAML that fails roles manifest validation
        '404':
          description: >-
            Organization not found, the caller may not update its roles, or the
            deployment is not self-hosted. The response does not say which.
        '409':
          description: >-
            The request came from an API key, and the manifest would leave no
            onboarded, active member able to manage roles and revoke API keys
      security:
        - ControlPlaneApiKey: []
components:
  schemas:
    PutRolesManifestRequest:
      type: object
      properties:
        yaml_content:
          type: string
          minLength: 1
          description: >-
            The roles manifest, as YAML. It must parse and pass roles manifest
            validation.
      required:
        - yaml_content
      additionalProperties: false
      description: Request body for replacing an organization's roles manifest
    UpdateRolesManifestResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          $ref: '#/components/schemas/ManifestItem'
      required:
        - success
        - data
      additionalProperties: false
      description: The organization's roles manifest after the update
    ManifestItem:
      type: object
      properties:
        yaml_content:
          type: string
          description: The manifest, as the YAML it was saved with
        created_at:
          anyOf:
            - type: string
              format: date-time
            - type: string
          description: When this version was saved
      required:
        - yaml_content
        - created_at
      additionalProperties: false
      description: One version of a manifest
  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

- [Roles](https://docs.honeyhive.ai/v2/cli-reference/ref/roles.md)
- [Roles Methods](https://docs.honeyhive.ai/v2/control-plane-sdk-reference/typescript/ref/roles/index.md)
- [Namespaces](https://docs.honeyhive.ai/v2/control-plane-sdk-reference/typescript/ref/namespaces.md)


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