# Space Membership

A *Space Membership* is a record of which *SpaceRole*s a person holds in a given *Space*. One person can belong to several *Space*s, and the permissions may differ per *Space*, so each combination of a person, a *Space*, and a set of permissions corresponds to one *Space Membership*. Unlike *Organization Membership*, which brings in a new person by inviting them by email, a *Space Membership* adds an existing user with a `user` reference and grants permissions through `roles` (an array of *SpaceRole* references). It is not an email invitation.

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

## Resource structure {#resource-structure}

The following is the single-read response for one *Space Membership*. `sys` (system properties) holds the user (`user`) and the *Space* (`space`) this membership points to, and it has the body property `roles` (the set of permissions).

```json
{
  "sys": {
    "id": "3trmXRM3RqbgSnifyg7PAm5memEx0",
    "type": "SpaceMembership",
    "space": { "sys": { "id": "tcq4V2Xb", "type": "Refer", "targetType": "Space" } },
    "user": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
    "createdBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
    "createdAt": "2026-06-14T14:56:04.737Z",
    "updatedBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
    "updatedAt": "2026-06-14T14:56:04.737Z",
    "version": 1
  },
  "roles": [
    { "sys": { "id": "3trmXRM3RqbgSnifyg7PAlm4FWTPQ8", "type": "Refer", "targetType": "SpaceRole" } }
  ]
}
```

Key properties:

- `space`: A `Refer<Space>` that points to the *Space* this membership belongs to.
- `user`: A `Refer<User>` that points to the user of this membership. The user you add as a member is bound here.
- `roles`: The set of permissions this user has in the *Space*. It is an array of `Refer<SpaceRole>` pointing to *SpaceRole*s, so one member can hold several *SpaceRole*s at once.

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

Every *Space Membership* carries common system properties in the `sys` object. `space`, `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 a *Space Membership* this is always `"SpaceMembership"`. |
| `space` | Refer&lt;Space&gt; | The *Space* this membership belongs to. |
| `user` | Refer&lt;User&gt; | The user 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 |
|---|---|---|
| `roles` | Refer&lt;SpaceRole&gt;[] | The member's set of permissions. An array of `Refer` pointing to *SpaceRole*s, holding 1 to 3 entries. One member can hold several *SpaceRole*s. |

A *Space 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. Adding a member (create) and delete do not have this header.

```api-endpoint
{
  "title": "List Space Memberships",
  "method": "GET",
  "path": "/spaces/{spaceId}/space-memberships",
  "description": "Reads the member memberships of one Space, page by page.",
  "responseStatus": 200,
  "baseUrl": "https://cma.weegloo.com/v1",
  "pathParameterSchema": {
    "spaceId": { "type": "string", "description": "The sys.id of the Space", "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": "3trmXRM3RqbgSnifyg7PAm5memEx0",
          "type": "SpaceMembership",
          "space": { "sys": { "id": "tcq4V2Xb", "type": "Refer", "targetType": "Space" } },
          "user": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
          "createdBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
          "createdAt": "2026-06-14T14:56:04.737Z",
          "updatedBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
          "updatedAt": "2026-06-14T14:56:04.737Z",
          "version": 1
        },
        "roles": [
          { "sys": { "id": "3trmXRM3RqbgSnifyg7PAlm4FWTPQ8", "type": "Refer", "targetType": "SpaceRole" } }
        ]
      }
    ],
    "links": { "self": "/v1/spaces/tcq4V2Xb/space-memberships" }
  }
}
```

```api-endpoint
{
  "title": "List my Space memberships",
  "method": "GET",
  "path": "/me/space-memberships",
  "description": "Reads the list of Space memberships the currently logged-in user belongs to. Send include=1 to also get the details of the Space 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 Space 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": "3trmXRM3RqbgSnifyg7PAm5memEx0",
          "type": "SpaceMembership",
          "space": { "sys": { "id": "tcq4V2Xb", "type": "Refer", "targetType": "Space" } },
          "user": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
          "createdBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
          "createdAt": "2026-06-14T14:56:04.737Z",
          "updatedBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
          "updatedAt": "2026-06-14T14:56:04.737Z",
          "version": 1
        },
        "roles": [
          { "sys": { "id": "3trmXRM3RqbgSnifyg7PAlm4FWTPQ8", "type": "Refer", "targetType": "SpaceRole" } }
        ]
      }
    ],
    "links": { "self": "/v1/me/space-memberships" }
  }
}
```

```api-endpoint
{
  "title": "Read a single Space Membership",
  "method": "GET",
  "path": "/spaces/{spaceId}/space-memberships/{spaceMembershipId}",
  "description": "Reads one Space Membership by sys.id.",
  "responseStatus": 200,
  "baseUrl": "https://cma.weegloo.com/v1",
  "pathParameterSchema": {
    "spaceId": { "type": "string", "description": "The sys.id of the Space", "required": true },
    "spaceMembershipId": { "type": "string", "description": "The sys.id of the Space 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": "3trmXRM3RqbgSnifyg7PAm5memEx0",
      "type": "SpaceMembership",
      "space": { "sys": { "id": "tcq4V2Xb", "type": "Refer", "targetType": "Space" } },
      "user": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
      "createdBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
      "createdAt": "2026-06-14T14:56:04.737Z",
      "updatedBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
      "updatedAt": "2026-06-14T14:56:04.737Z",
      "version": 1
    },
    "roles": [
      { "sys": { "id": "3trmXRM3RqbgSnifyg7PAlm4FWTPQ8", "type": "Refer", "targetType": "SpaceRole" } }
    ]
  }
}
```

```api-endpoint
{
  "title": "Add a Space Membership member (create)",
  "method": "POST",
  "path": "/spaces/{spaceId}/space-memberships",
  "description": "Adds an existing user as a Space member with a user reference. The body holds the user to add and the roles to grant (1 to 3 SpaceRole references).",
  "responseStatus": 201,
  "baseUrl": "https://cma.weegloo.com/v1",
  "pathParameterSchema": {
    "spaceId": { "type": "string", "description": "The sys.id of the Space", "required": true }
  },
  "requestHeaderSchema": {
    "Authorization": { "type": "string", "description": "Bearer token (CMA authentication)" }
  },
  "requestBodySchema": {
    "type": "object",
    "required": ["user", "roles"],
    "properties": {
      "user": {
        "type": "object",
        "description": "A Refer<User> pointing to the user to add",
        "properties": {
          "sys": {
            "type": "object",
            "properties": {
              "id": { "type": "string", "description": "The sys.id of the User" },
              "type": { "type": "string", "enum": ["Refer"] },
              "targetType": { "type": "string", "enum": ["User"] }
            }
          }
        }
      },
      "roles": {
        "type": "array",
        "description": "An array of SpaceRole references to grant (1 to 3)",
        "minItems": 1,
        "maxItems": 3,
        "items": {
          "type": "object",
          "properties": {
            "sys": {
              "type": "object",
              "properties": {
                "id": { "type": "string", "description": "The sys.id of the SpaceRole" },
                "type": { "type": "string", "enum": ["Refer"] },
                "targetType": { "type": "string", "enum": ["SpaceRole"] }
              }
            }
          }
        }
      }
    },
    "example": {
      "user": { "sys": { "id": "3trmXRM3RqbgSnifyg7PVusr01Ex", "type": "Refer", "targetType": "User" } },
      "roles": [
        { "sys": { "id": "3trmXRM3RqbgSnifyg7PLzmhWFANg9", "type": "Refer", "targetType": "SpaceRole" } }
      ]
    }
  },
  "responseExample": {
    "sys": {
      "id": "3trmXRM3RqbgSnifyg7PVsmb01Ex",
      "type": "SpaceMembership",
      "space": { "sys": { "id": "tcq4V2Xb", "type": "Refer", "targetType": "Space" } },
      "user": { "sys": { "id": "3trmXRM3RqbgSnifyg7PVusr01Ex", "type": "Refer", "targetType": "User" } },
      "createdBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
      "createdAt": "2026-06-18T11:20:00.000Z",
      "updatedBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
      "updatedAt": "2026-06-18T11:20:00.000Z",
      "version": 1
    },
    "roles": [
      { "sys": { "id": "3trmXRM3RqbgSnifyg7PLzmhWFANg9", "type": "Refer", "targetType": "SpaceRole" } }
    ]
  }
}
```

```api-endpoint
{
  "title": "Update a Space Membership's roles",
  "method": "PUT",
  "path": "/spaces/{spaceId}/space-memberships/{spaceMembershipId}",
  "description": "Updates a member's roles. The body holds only roles. You must carry the current sys.version in the X-Weegloo-Version header.",
  "responseStatus": 200,
  "baseUrl": "https://cma.weegloo.com/v1",
  "pathParameterSchema": {
    "spaceId": { "type": "string", "description": "The sys.id of the Space", "required": true },
    "spaceMembershipId": { "type": "string", "description": "The sys.id of the Space 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": ["roles"],
    "properties": {
      "roles": {
        "type": "array",
        "description": "An array of SpaceRole references to change to (1 to 3)",
        "minItems": 1,
        "maxItems": 3,
        "items": {
          "type": "object",
          "properties": {
            "sys": {
              "type": "object",
              "properties": {
                "id": { "type": "string", "description": "The sys.id of the SpaceRole" },
                "type": { "type": "string", "enum": ["Refer"] },
                "targetType": { "type": "string", "enum": ["SpaceRole"] }
              }
            }
          }
        }
      }
    },
    "example": {
      "roles": [
        { "sys": { "id": "3trmXRM3RqbgSnifyg7PLzmhWFANg9", "type": "Refer", "targetType": "SpaceRole" } }
      ]
    }
  },
  "responseExample": {
    "sys": {
      "id": "3trmXRM3RqbgSnifyg7PVsmb01Ex",
      "type": "SpaceMembership",
      "space": { "sys": { "id": "tcq4V2Xb", "type": "Refer", "targetType": "Space" } },
      "user": { "sys": { "id": "3trmXRM3RqbgSnifyg7PVusr01Ex", "type": "Refer", "targetType": "User" } },
      "createdBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
      "createdAt": "2026-06-18T11:20:00.000Z",
      "updatedBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
      "updatedAt": "2026-06-18T11:21:00.000Z",
      "version": 2
    },
    "roles": [
      { "sys": { "id": "3trmXRM3RqbgSnifyg7PLzmhWFANg9", "type": "Refer", "targetType": "SpaceRole" } }
    ]
  }
}
```

```api-endpoint
{
  "title": "Partially update a Space Membership (JSON Patch)",
  "method": "PATCH",
  "path": "/spaces/{spaceId}/space-memberships/{spaceMembershipId}",
  "description": "Updates a member's roles 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": {
    "spaceId": { "type": "string", "description": "The sys.id of the Space", "required": true },
    "spaceMembershipId": { "type": "string", "description": "The sys.id of the Space 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: /roles/- (append to the end of the array)" },
        "value": { "description": "The value used by add/replace/test" },
        "from": { "type": "string", "description": "The source location for move/copy" }
      }
    },
    "example": [
      { "op": "add", "path": "/roles/-", "value": { "sys": { "id": "3trmXRM3RqbgSnifyg7PLzmhWFANg9", "type": "Refer", "targetType": "SpaceRole" } } }
    ]
  },
  "responseExample": {
    "sys": {
      "id": "3trmXRM3RqbgSnifyg7PVsmb01Ex",
      "type": "SpaceMembership",
      "space": { "sys": { "id": "tcq4V2Xb", "type": "Refer", "targetType": "Space" } },
      "user": { "sys": { "id": "3trmXRM3RqbgSnifyg7PVusr01Ex", "type": "Refer", "targetType": "User" } },
      "createdBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
      "createdAt": "2026-06-18T11:20:00.000Z",
      "updatedBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
      "updatedAt": "2026-06-18T11:22:00.000Z",
      "version": 3
    },
    "roles": [
      { "sys": { "id": "3trmXRM3RqbgSnifyg7PAlm4FWTPQ8", "type": "Refer", "targetType": "SpaceRole" } },
      { "sys": { "id": "3trmXRM3RqbgSnifyg7PLzmhWFANg9", "type": "Refer", "targetType": "SpaceRole" } }
    ]
  }
}
```

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

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

## Related documents {#related-documents}

- [SpaceRole](/api/reference/cma/space-role.md): The definition of the *SpaceRole* (the set of permissions) you put in `roles`.
- [Space](/api/reference/cma/space.md): The *Space* this membership belongs to.
- [Organization Membership](/api/reference/cma/organization-membership.md): Members and roles at the *Organization* level.