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

# Roles

> Read and replace an organization's roles manifest, which defines its roles and the permissions each one grants. Available on self-hosted deployments only.

## Schema introspection

Every command below with arguments supports two read-only flags for tooling and AI agents:

* `--show-file-schema`: print the JSON Schema for the full request object (the format `--filename` accepts).
* `--show-argument-schema <flag-name>`: print the JSON Schema for one argument's value. Pass the kebab flag name **without** the leading `--` (e.g. `org-id`, not `--org-id`).

Both write pure JSON to stdout and never call the API. They cannot be combined with any other command-specific flag.

## `get`

Get an organization's roles manifest

Return the latest version of an organization's roles manifest: the YAML that defines its
roles and the permissions each one grants, as the organization settings page in the
HoneyHive app shows it. The organization is identified by the `org_id` path parameter
alone. The `x-hh-org-id` header does not participate.

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.

### Usage

```sh theme={null}
honeyhive roles get [options]
```

**Accepted keys:** [Control plane fine-grained API key](https://docs.honeyhive.ai/v2/workspace/api-keys.md#key-types)

### Options

| Flag | Type | Required | Description |
| - | - | - | - |
| `--org-id` | string | yes | The unique identifier of the organization |

Also supports `--show-file-schema`, `--show-argument-schema <flag-name>`, and `--filename`. See [Schema introspection](#schema-introspection) for details.

## `update`

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.

### Usage

```sh theme={null}
honeyhive roles update [options]
```

**Accepted keys:** [Control plane fine-grained API key](https://docs.honeyhive.ai/v2/workspace/api-keys.md#key-types)

### Options

| Flag | Type | Required | Description |
| - | - | - | - |
| `--org-id` | string | yes | The unique identifier of the organization |
| `--yaml-content` | string | yes | The roles manifest, as YAML. It must parse and pass roles manifest validation. |

Also supports `--show-file-schema`, `--show-argument-schema <flag-name>`, and `--filename`. See [Schema introspection](#schema-introspection) for details.


## Related topics

- [Roles Methods](https://docs.honeyhive.ai/v2/control-plane-sdk-reference/typescript/ref/roles/index.md)
- [Role Based Access Control](https://docs.honeyhive.ai/v2/workspace/roles.md)
- [SSO Group Role Mapping](https://docs.honeyhive.ai/v2/workspace/sso-group-role-mapping.md)


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