> ## Documentation Index
> Fetch the complete documentation index at: https://datum-4926dda5-docs-api-reference-demo.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# OrganizationMembership

> OrganizationMembership establishes a user's membership in an organization and optionally assigns roles to grant permissions.

<Note>
  API resource reference for **OrganizationMembership**, part of the [Resource Manager service](/api/resource-manager/overview). To create or change one, see [Changing resources](/datumctl/resources/changing); to inspect, see [Reading resources](/datumctl/resources/reading).
</Note>

<Warning>
  This resource is part of the `v1alpha1` API and is subject to change. Fields and behavior may change in future releases.
</Warning>

## Identity

|         |                                |
| ------- | ------------------------------ |
| Group   | `resourcemanager.miloapis.com` |
| Version | `v1alpha1`                     |
| Kind    | `OrganizationMembership`       |
| Scope   | Project                        |

## Overview

An `OrganizationMembership` connects a user to an organization and, optionally, grants that user one or more roles within it. Creating a membership establishes the user-organization relationship; listing roles on the membership grants the corresponding permissions.

Use it whenever you want to add someone to an organization or adjust what they can do there. When you assign roles, the controller automatically creates and manages the underlying `PolicyBinding` resources for each role, so you manage access in one place. Roles can be added or removed at any time after the membership exists. The referenced user, organization, and roles must already exist before you create the membership.

## Spec fields

| Field                       | Type      | Required | Description                                                                                                                                           |
| --------------------------- | --------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `spec.organizationRef`      | Object    | Yes      | Identifies the organization to grant membership in. The organization must exist beforehand.                                                           |
| `spec.organizationRef.name` | string    | Yes      | Name of the referenced organization.                                                                                                                  |
| `spec.userRef`              | Object    | Yes      | Identifies the user to grant organization membership. The user must exist beforehand.                                                                 |
| `spec.userRef.name`         | string    | Yes      | Name of the referenced user.                                                                                                                          |
| `spec.roles`                | \[]Object | No       | List of roles to assign to the user within the organization. Omit or leave empty to establish membership with no roles. Duplicate roles are rejected. |
| `spec.roles[].name`         | string    | Yes      | Name of the referenced role.                                                                                                                          |
| `spec.roles[].namespace`    | string    | No       | Location of the referenced role. Defaults to the membership's own location if not set.                                                                |

## Status fields (read-only)

| Field                       | Type      | Description                                                                                                                                                                                                                                           |
| --------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `status.appliedRoles`       | \[]Object | Per-role reconciliation state for each entry in `spec.roles`. Each entry records `name`, `namespace`, `status` (`Applied`, `Pending`, or `Failed`), a `policyBindingRef` and `appliedAt` timestamp when applied, and a `message` explaining failures. |
| `status.conditions`         | \[]Object | Tracks state such as `Ready` (membership established) and `RolesApplied` (whether all roles were successfully applied).                                                                                                                               |
| `status.observedGeneration` | integer   | The most recent membership spec generation the controller has processed.                                                                                                                                                                              |
| `status.organization`       | Object    | Cached information about the referenced organization, populated by the controller.                                                                                                                                                                    |
| `status.user`               | Object    | Cached information about the referenced user, populated by the controller.                                                                                                                                                                            |

## Usage

```yaml theme={null}
apiVersion: resourcemanager.miloapis.com/v1alpha1
kind: OrganizationMembership
metadata:
  name: jane-acme-membership
spec:
  organizationRef:
    name: acme-corp
  userRef:
    name: jane-doe
  roles:
    - name: organization-viewer
      namespace: organization-acme-corp
```

```bash theme={null}
datumctl apply -f organizationmembership.yaml --project my-project
datumctl get organizationmemberships --project my-project
datumctl describe organizationmembership jane-acme-membership --project my-project
```

<Tip>
  Run `datumctl explain organizationmemberships --recursive` to see the full, live field tree for this resource.
</Tip>