# Organization Membership

An *Organization Membership* is a record of which *Organization* a person belongs to and with what permission level (`role`). One person can belong to several *Organization*s, and the permission may differ per *Organization*, so each combination of a person, an organization, and a permission corresponds to one *Organization Membership*. You add a new member by inviting them by email (the [invite (create)](#api) endpoint below). When you create an invitation, the person at that email joins the *Organization* with that `role`.

You read the list of *Organization*s you belong to with [GET /me/organization-memberships](/api/reference/cma/organization-membership.md). If you also send `include=1`, the details of the *Organization* it points to are included in the response.

## Resource structure {#resource-structure}

The following is the single-read response for one *Organization Membership*. `sys` (system properties) holds the person (`user`) and organization (`organization`) this membership points to, and it has the body property `role`.

```json
{
  "sys": {
    "id": "3trmXRL6dW1QKblBXOc8nXAVz4kPXd",
    "type": "OrganizationMembership",
    "organization": { "sys": { "id": "ilLRJxDp", "type": "Refer", "targetType": "Organization" } },
    "user": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
    "createdBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
    "createdAt": "2026-05-11T10:51:16.841Z",
    "updatedBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
    "updatedAt": "2026-05-11T10:51:16.841Z",
    "version": 1
  },
  "role": "OWNER"
}
```

Key properties:

- `organization`: A `Refer<Organization>` that points to the *Organization* this membership belongs to.
- `user`: A `Refer<User>` that points to the person of this membership. When the invited person joins, that user is bound here.
- `role`: The permission level this person has in the *Organization*. One of `OWNER`, `ADMIN`, or `MEMBER`.

## System properties (sys) and body {#system-properties-sys-and-body}

Every *Organization Membership* carries common system properties in the `sys` object. `organization`, `user`, `createdBy`, and `updatedBy` are in the `Refer` shape (`{ "sys": { "id", "type": "Refer", "targetType" } }`).

| Property | Type | Description |
|---|---|---|
| `id` | string | Unique resource identifier. |
| `type` | string | Resource kind. For an *Organization Membership* this is always `"OrganizationMembership"`. |
| `organization` | Refer&lt;Organization&gt; | The *Organization* this membership belongs to. |
| `user` | Refer&lt;User&gt; | The person of this membership. |
| `createdBy` | Refer&lt;User&gt; | The user who created it. |
| `createdAt` | string (date-time) | Creation time. |
| `updatedBy` | Refer&lt;User&gt; | The user who last updated it. |
| `updatedAt` | string (date-time) | Last update time. |
| `version` | integer (≥1) | Resource version. It increases by 1 with every change. |

Body properties:

| Property | Type | Description |
|---|---|---|
| `role` | string (enum) | The member's permission level. One of `OWNER`, `ADMIN`, or `MEMBER`. |

The three values of `role` mean the following.

- `OWNER`: The owner level of the *Organization*.
- `ADMIN`: The administrator level of the *Organization*.
- `MEMBER`: The regular member level of the *Organization*.

An *Organization Membership* is a settings resource with no publishing concept. So unlike *Content* and *Media*, its `sys` has no `publish`, `archive`, or `status`, only `version`. The `version` increases each time you update the membership.

## API {#api}

The base URL for all endpoints below is `https://cma.weegloo.com/v1`, and a Bearer token that authenticates against CMA is required in the `Authorization` header. Role updates (`PUT`, `PATCH`) must also send the `X-Weegloo-Version` header (the current resource's `sys.version`) for optimistic concurrency control. Invite (create) and delete do not have this header.

```api-endpoint
{
  "title": "List Organization Memberships",
  "method": "GET",
  "path": "/organizations/{organizationId}/organization-memberships",
  "description": "Reads the member memberships of one Organization, page by page.",
  "responseStatus": 200,
  "baseUrl": "https://cma.weegloo.com/v1",
  "pathParameterSchema": {
    "organizationId": { "type": "string", "description": "The sys.id of the Organization", "required": true }
  },
  "queryParameterSchema": {
    "limit": { "type": "integer", "description": "Number of items to return per page (1-100)", "default": 15 },
    "skip": { "type": "integer", "description": "Number of items to skip", "default": 0 },
    "next": { "type": "string", "description": "Next-page cursor (the value from links.next in the previous response)" },
    "prev": { "type": "string", "description": "Previous-page cursor (the value from links.prev in the previous response)" },
    "order": { "type": "string", "description": "Sort criteria. Multiple sorts separated by commas (e.g. sys.createdAt,sys.id)", "default": "sys.createdAt,sys.id" },
    "select": { "type": "string", "description": "Fields to include (sys.id,sys.createdAt) or exclude (-sys.id). Do not mix inclusion and exclusion." },
    "include": { "type": "integer", "description": "Related-resource inclusion level. 0=default, 1=related resources, 2=nested relations, 3=full", "default": 0 }
  },
  "additionalQueryParams": true,
  "requestHeaderSchema": {
    "Authorization": { "type": "string", "description": "Bearer token (CMA authentication)" }
  },
  "responseExample": {
    "sys": { "type": "TotalPageResponse" },
    "limit": 15,
    "totalCount": 1,
    "items": [
      {
        "sys": {
          "id": "3trmXRL6dW1QKblBXOc8nXAVz4kPXd",
          "type": "OrganizationMembership",
          "organization": { "sys": { "id": "ilLRJxDp", "type": "Refer", "targetType": "Organization" } },
          "user": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
          "createdBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
          "createdAt": "2026-05-11T10:51:16.841Z",
          "updatedBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
          "updatedAt": "2026-05-11T10:51:16.841Z",
          "version": 1
        },
        "role": "OWNER"
      }
    ],
    "links": { "self": "/v1/organizations/ilLRJxDp/organization-memberships" }
  }
}
```

```api-endpoint
{
  "title": "List my Organization memberships",
  "method": "GET",
  "path": "/me/organization-memberships",
  "description": "Reads the list of Organization memberships the currently logged-in user belongs to. Send include=1 to also get the details of the Organization each one points to.",
  "responseStatus": 200,
  "baseUrl": "https://cma.weegloo.com/v1",
  "pathParameterSchema": {},
  "queryParameterSchema": {
    "limit": { "type": "integer", "description": "Number of items to return per page (1-100)", "default": 15 },
    "skip": { "type": "integer", "description": "Number of items to skip", "default": 0 },
    "next": { "type": "string", "description": "Next-page cursor (the value from links.next in the previous response)" },
    "prev": { "type": "string", "description": "Previous-page cursor (the value from links.prev in the previous response)" },
    "order": { "type": "string", "description": "Sort criteria. Multiple sorts separated by commas (e.g. sys.createdAt,sys.id)", "default": "sys.createdAt,sys.id" },
    "include": { "type": "integer", "description": "Related-resource inclusion level. 0=default, 1=related resources (includes Organization details), 2=nested relations, 3=full", "default": 0 },
    "select": { "type": "string", "description": "Fields to include (sys.id,sys.createdAt) or exclude (-sys.id). Do not mix inclusion and exclusion." }
  },
  "requestHeaderSchema": {
    "Authorization": { "type": "string", "description": "Bearer token (CMA authentication)" }
  },
  "responseExample": {
    "sys": { "type": "TotalPageResponse" },
    "limit": 15,
    "totalCount": 1,
    "items": [
      {
        "sys": {
          "id": "3trmXRL6dW1QKblBXOc8nXAVz4kPXd",
          "type": "OrganizationMembership",
          "organization": { "sys": { "id": "ilLRJxDp", "type": "Refer", "targetType": "Organization" } },
          "user": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
          "createdBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
          "createdAt": "2026-05-11T10:51:16.841Z",
          "updatedBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
          "updatedAt": "2026-05-11T10:51:16.841Z",
          "version": 1
        },
        "role": "OWNER"
      }
    ],
    "links": { "self": "/v1/me/organization-memberships" }
  }
}
```

```api-endpoint
{
  "title": "Read a single Organization Membership",
  "method": "GET",
  "path": "/organizations/{organizationId}/organization-memberships/{membershipId}",
  "description": "Reads one Organization Membership by sys.id.",
  "responseStatus": 200,
  "baseUrl": "https://cma.weegloo.com/v1",
  "pathParameterSchema": {
    "organizationId": { "type": "string", "description": "The sys.id of the Organization", "required": true },
    "membershipId": { "type": "string", "description": "The sys.id of the Organization Membership", "required": true }
  },
  "queryParameterSchema": {
    "include": { "type": "integer", "description": "Related-resource inclusion level. 0=default, 1=related resources, 2=nested relations, 3=full", "default": 0 }
  },
  "requestHeaderSchema": {
    "Authorization": { "type": "string", "description": "Bearer token (CMA authentication)" }
  },
  "responseExample": {
    "sys": {
      "id": "3trmXRL6dW1QKblBXOc8nXAVz4kPXd",
      "type": "OrganizationMembership",
      "organization": { "sys": { "id": "ilLRJxDp", "type": "Refer", "targetType": "Organization" } },
      "user": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
      "createdBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
      "createdAt": "2026-05-11T10:51:16.841Z",
      "updatedBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
      "updatedAt": "2026-05-11T10:51:16.841Z",
      "version": 1
    },
    "role": "OWNER"
  }
}
```

```api-endpoint
{
  "title": "Invite an Organization Membership (create)",
  "method": "POST",
  "path": "/organizations/{organizationId}/organization-memberships",
  "description": "Invites a person by email to add them as an Organization member. The body holds the email of the person to invite and the role to grant.",
  "responseStatus": 201,
  "baseUrl": "https://cma.weegloo.com/v1",
  "pathParameterSchema": {
    "organizationId": { "type": "string", "description": "The sys.id of the Organization", "required": true }
  },
  "requestHeaderSchema": {
    "Authorization": { "type": "string", "description": "Bearer token (CMA authentication)" }
  },
  "requestBodySchema": {
    "type": "object",
    "required": ["email", "role"],
    "properties": {
      "email": { "type": "string", "format": "email", "description": "The email of the person to invite" },
      "role": { "type": "string", "enum": ["OWNER", "ADMIN", "MEMBER"], "description": "The permission level to grant" }
    },
    "example": {
      "email": "designer@dailywear.example",
      "role": "MEMBER"
    }
  },
  "responseExample": {
    "sys": {
      "id": "3trmXRM3RqbgSnifyg7PVmem01Ex",
      "type": "OrganizationMembership",
      "organization": { "sys": { "id": "ilLRJxDp", "type": "Refer", "targetType": "Organization" } },
      "user": { "sys": { "id": "3trmXRM3RqbgSnifyg7PVusr01Ex", "type": "Refer", "targetType": "User" } },
      "createdBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
      "createdAt": "2026-06-18T11:15:00.000Z",
      "updatedBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
      "updatedAt": "2026-06-18T11:15:00.000Z",
      "version": 1
    },
    "role": "MEMBER"
  }
}
```

```api-endpoint
{
  "title": "Update an Organization Membership role",
  "method": "PUT",
  "path": "/organizations/{organizationId}/organization-memberships/{membershipId}",
  "description": "Updates a member's role. The body holds only role. You must carry the current sys.version in the X-Weegloo-Version header.",
  "responseStatus": 200,
  "baseUrl": "https://cma.weegloo.com/v1",
  "pathParameterSchema": {
    "organizationId": { "type": "string", "description": "The sys.id of the Organization", "required": true },
    "membershipId": { "type": "string", "description": "The sys.id of the Organization Membership", "required": true }
  },
  "requestHeaderSchema": {
    "Authorization": { "type": "string", "description": "Bearer token (CMA authentication)" },
    "X-Weegloo-Version": { "type": "integer", "description": "The current resource's sys.version (optimistic concurrency control)" }
  },
  "requestBodySchema": {
    "type": "object",
    "required": ["role"],
    "properties": {
      "role": { "type": "string", "enum": ["OWNER", "ADMIN", "MEMBER"], "description": "The permission level to change to" }
    },
    "example": {
      "role": "ADMIN"
    }
  },
  "responseExample": {
    "sys": {
      "id": "3trmXRM3RqbgSnifyg7PVmem01Ex",
      "type": "OrganizationMembership",
      "organization": { "sys": { "id": "ilLRJxDp", "type": "Refer", "targetType": "Organization" } },
      "user": { "sys": { "id": "3trmXRM3RqbgSnifyg7PVusr01Ex", "type": "Refer", "targetType": "User" } },
      "createdBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
      "createdAt": "2026-06-18T11:15:00.000Z",
      "updatedBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
      "updatedAt": "2026-06-18T11:16:00.000Z",
      "version": 2
    },
    "role": "ADMIN"
  }
}
```

```api-endpoint
{
  "title": "Partially update an Organization Membership (JSON Patch)",
  "method": "PATCH",
  "path": "/organizations/{organizationId}/organization-memberships/{membershipId}",
  "description": "Updates a member's role with RFC 6902 JSON Patch. The request Content-Type header must be application/json-patch+json. You must carry the current sys.version in the X-Weegloo-Version header.",
  "responseStatus": 200,
  "baseUrl": "https://cma.weegloo.com/v1",
  "requestContentType": "application/json-patch+json",
  "pathParameterSchema": {
    "organizationId": { "type": "string", "description": "The sys.id of the Organization", "required": true },
    "membershipId": { "type": "string", "description": "The sys.id of the Organization Membership", "required": true }
  },
  "requestHeaderSchema": {
    "Authorization": { "type": "string", "description": "Bearer token (CMA authentication)" },
    "Content-Type": { "type": "string", "description": "application/json-patch+json (RFC 6902 JSON Patch)" },
    "X-Weegloo-Version": { "type": "integer", "description": "The current resource's sys.version (optimistic concurrency control)" }
  },
  "requestBodySchema": {
    "type": "array",
    "description": "An array of RFC 6902 JSON Patch operations (op / path / value / from). path is an RFC 6901 JSON Pointer.",
    "items": {
      "type": "object",
      "required": ["op", "path"],
      "properties": {
        "op": { "type": "string", "enum": ["add", "remove", "replace", "move", "copy", "test"], "description": "Operation kind" },
        "path": { "type": "string", "description": "Target location (JSON Pointer). Example: /role" },
        "value": { "description": "The value used by add/replace/test" },
        "from": { "type": "string", "description": "The source location for move/copy" }
      }
    },
    "example": [
      { "op": "replace", "path": "/role", "value": "MEMBER" }
    ]
  },
  "responseExample": {
    "sys": {
      "id": "3trmXRM3RqbgSnifyg7PVmem01Ex",
      "type": "OrganizationMembership",
      "organization": { "sys": { "id": "ilLRJxDp", "type": "Refer", "targetType": "Organization" } },
      "user": { "sys": { "id": "3trmXRM3RqbgSnifyg7PVusr01Ex", "type": "Refer", "targetType": "User" } },
      "createdBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
      "createdAt": "2026-06-18T11:15:00.000Z",
      "updatedBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
      "updatedAt": "2026-06-18T11:17:00.000Z",
      "version": 3
    },
    "role": "MEMBER"
  }
}
```

```api-endpoint
{
  "title": "Delete an Organization Membership (remove a member)",
  "method": "DELETE",
  "path": "/organizations/{organizationId}/organization-memberships/{membershipId}",
  "description": "Removes a member from the Organization. On success it responds with 204 No Content and no response body.",
  "responseStatus": 204,
  "baseUrl": "https://cma.weegloo.com/v1",
  "pathParameterSchema": {
    "organizationId": { "type": "string", "description": "The sys.id of the Organization", "required": true },
    "membershipId": { "type": "string", "description": "The sys.id of the Organization Membership", "required": true }
  },
  "requestHeaderSchema": {
    "Authorization": { "type": "string", "description": "Bearer token (CMA authentication)" }
  }
}
```

```api-endpoint
{
  "title": "Leave an Organization (delete my membership)",
  "method": "DELETE",
  "path": "/me/organization-memberships/{organizationMembershipId}",
  "description": "The currently logged-in user leaves this Organization on their own. On success it responds with 204 No Content and no response body.",
  "responseStatus": 204,
  "baseUrl": "https://cma.weegloo.com/v1",
  "pathParameterSchema": {
    "organizationMembershipId": { "type": "string", "description": "The sys.id of the Organization Membership to leave", "required": true }
  },
  "requestHeaderSchema": {
    "Authorization": { "type": "string", "description": "Bearer token (CMA authentication)" }
  }
}
```

## Related documents {#related-documents}

- [Organization](/api/reference/cma/organization.md): The *Organization* this membership points to.
- [Space Membership](/api/reference/cma/space-membership.md): Members and roles at the *Space* level.