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

# Org Members

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

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

## `list`

List an organization's members

Return one page of an organization's members, oldest membership first. Each member carries
their roles in the organization and whether they have signed in yet. 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 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.

### Usage

```sh theme={null}
honeyhive org-members list [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 |
| `--limit` | number | no | Number of members to return per page |
| `--page` | number | no | 1-indexed page number |

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

## `create`

Invite someone to an organization

Invite one email address to an organization, and return the member. The address is stored
lowercased. An address with no HoneyHive user yet gets one, and the invitee receives an
email. An email sent for a request made with an API key names the inviter as a HoneyHive
teammate.

The new member has no roles, and is `INVITED` until they first sign in. Sign-in keeps any
roles set before then and adds the roles the organization's roles manifest gives invited
members. To give them roles now, set their roles with the `user_id` this returns.

Inviting an address that is already a member returns that member unchanged, and sends no
email, so sending the same invite again is safe. 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 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.

### Usage

```sh theme={null}
honeyhive org-members create [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 |
| - | - | - | - |
| `--email` | string | yes | The address to invite. It is stored lowercased, because sign-in matches addresses that way |
| `--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`

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.

### Usage

```sh theme={null}
honeyhive org-members 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 |
| `--role-names` | json | yes | 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 |
| `--user-id` | string | yes | The member's user id, as the member list returns it. One person has the same user id in every organization, workspace and project |

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

## `delete`

Remove someone from an organization

Remove a user from an organization and from every virtual data plane, workspace and project
in it, which also withdraws a pending invite. The user's current sessions must reauthorize.
Their HoneyHive user stays, along with their memberships of other organizations. The
organization and the user are identified by the path parameters alone. The `x-hh-org-id`
header does not participate.

When an API key makes the request, it cannot remove a member who has signed in and whose
roles grant `org.roles.get`, `org.roles.set`, `org.fine_grained_api_key_cp.list` and
`org.fine_grained_api_key_cp.delete`, so someone in the organization can always revoke the
key. Such a request is refused with 409, and the member has to be removed in the HoneyHive
app. A member who has not signed in yet can be removed with an API key whatever their roles.
When the organization has no valid roles manifest in force, a member who has signed in
cannot be checked, and an API key's request to remove them is refused with 409.

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.

### Usage

```sh theme={null}
honeyhive org-members delete [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 |
| `--user-id` | string | yes | The member's user id, as the member list returns it. One person has the same user id in every organization, workspace and project |

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


## Related topics

- [Org Members Methods](https://docs.honeyhive.ai/v2/control-plane-sdk-reference/typescript/ref/org-members/index.md)
- [CreateOrgMemberResponse](https://docs.honeyhive.ai/v2/control-plane-sdk-reference/typescript/ref/org-members/CreateOrgMemberResponse.md)
- [DeleteOrgMemberResponse](https://docs.honeyhive.ai/v2/control-plane-sdk-reference/typescript/ref/org-members/DeleteOrgMemberResponse.md)


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