# Organization

An *Organization* is the top-level container that holds *Space*s. A company or a team corresponds to one *Organization*, and several *Space*s live under it. The subscription plan (`plan`) and membership are managed at the *Organization* level, so billing and member permissions apply based on this *Organization* rather than the *Space*.

You read the list of *Organization*s you belong to with [GET /me/organization-memberships](/api/reference/cma/organization-membership.md). This resource has no endpoint that returns the full list.

## Resource structure {#resource-structure}

The following is the single-read response for the *Organization* "DailyWear Company". It has `sys` (system properties) and the body properties `name` and `description`.

```json
{
  "sys": {
    "id": "ilLRJxDp",
    "type": "Organization",
    "createdBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
    "createdAt": "2026-05-11T10:51:16.832Z",
    "updatedBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
    "updatedAt": "2026-05-11T10:51:16.832Z",
    "version": 1,
    "isOfficial": false,
    "plan": { "sys": { "id": "free", "type": "Refer", "targetType": "Plan" } }
  },
  "name": "DailyWear Company",
  "description": "Company running an online clothing and accessories store"
}
```

Key properties:

- `name`: The name of the *Organization* (1-64 characters). It is the display name of the company or team.
- `description`: A description of the *Organization* (1-128 characters, optional).
- `plan`: A `Refer<Plan>` that points to this *Organization*'s subscription plan (e.g. `free`). The billing plan is tied here.
- `isOfficial`: Whether this is an official *Organization* (`boolean`).

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

Every *Organization* carries common system properties in the `sys` object. `createdBy` and `updatedBy` are in the `Refer` shape (`{ "sys": { "id", "type": "Refer", "targetType" } }`), and `plan` is a `Refer<Plan>`.

| Property | Type | Description |
|---|---|---|
| `id` | string | Unique resource identifier. |
| `type` | string | Resource kind. For an *Organization* this is always `"Organization"`. |
| `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. |
| `isOfficial` | boolean | Whether this is an official *Organization*. |
| `plan` | Refer&lt;Plan&gt; | The subscription plan. Example: `free`. |

Body properties:

| Property | Type | Description |
|---|---|---|
| `name` | string (1-64) | The *Organization* name. Specified on create and update. |
| `description` | string (1-128) | The *Organization* description. Optional. |
| `icon` | string (read) / object (write) | The *Organization* icon. In responses it is an image URL string. In update requests you send it as an object that points to an uploaded file: `{ "upload": { "sys": { ..., "targetType": "Upload" } } }` (a reference to an *Upload* obtained from the [Upload API](/api/reference/upload-api.md)). |
| `consoleHomeUrl` | string (uri) | The page shown in place of the default home screen, in every *Space* under this *Organization*. Give it an `https` URL that does not point to the console host ([conditions](#console-home-url-page)). Optional. |

An *Organization* 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 *Organization*.

Update (`PUT`) replaces the whole resource, and the two optional properties answer an omitted value differently. Leaving out `icon` keeps the stored icon, while leaving out `consoleHomeUrl` clears the stored URL. To keep a `consoleHomeUrl` that is already set, send it again with every update. Partial update (`PATCH`) touches only the properties named in the patch, so it leaves `consoleHomeUrl` alone unless you address it.

## What the page has to satisfy {#console-home-url-page}

A stored address does not mean the page renders. If you point it at an address that refuses to be shown, the update still succeeds, no error comes back, and the only symptom is that nothing appears on the home screen.

For the page to render in that spot, it has to satisfy the following.

- **Serve it over HTTPS.** The console runs on HTTPS, so the browser blocks a page on an insecure connection from rendering inside it.
- **Allow being rendered inside another page.** Set the response header `Content-Security-Policy: frame-ancestors https://console.weegloo.com`. If `X-Frame-Options` blocks it, adjust that as well.
- **If the page uses cookies, issue them with `SameSite=None; Secure`.** It renders inside another site, so a cookie without that attribute is never sent.

The page renders inside an `<iframe>`, and only the permissions below are open on that frame.

| Attribute | What it lets the page do |
|---|---|
| `sandbox="allow-scripts"` | Run scripts. |
| `sandbox="allow-same-origin"` | Read and write its own origin's cookies and storage, and call its own server. |
| `sandbox="allow-forms"` | Submit forms. |
| `sandbox="allow-popups"` | Open a new window or tab. |
| `sandbox="allow-popups-to-escape-sandbox"` | Keep a window opened that way from inheriting these restrictions. |
| `sandbox="allow-downloads"` | Start a file download. |
| `sandbox="allow-storage-access-by-user-activation"` | Request storage access after the user interacts with it. |
| `allow="fullscreen"` | Go fullscreen. |
| `allow="clipboard-write"` | Write to the clipboard. |

Anything not listed here does not work. No error is raised and the call is silently ignored, so code cannot tell whether it was blocked.

The frame also carries `referrerpolicy="strict-origin-when-cross-origin"`, so the page receives the console's origin and not the screen it was opened from.

Apart from `sandbox`, a page that requires a login may not work. Most login providers block signing in from inside another page, so social login generally does not work.

## Errors {#errors}

These are the codes you meet when working with an *Organization*. For codes that are common to every resource, see [common errors](/api/reference/common/errors.md).

| Code | Condition |
|---|---|
| `WGL422078` | The caller tried to delete an *Organization* that was not on the free plan. That *Organization* has to be moved down to the free plan first. |
| `WGL422079` | The caller tried to delete an *Organization* whose subscription had not been cancelled, or whose plan change was still pending. |
| `WGL422024` | The caller tried to delete an *Organization* that still had *Space*s in it. That *Organization* can be deleted only after every *Space* has been deleted. |
| `WGL422046` | The file uploaded as the `icon` exceeds the allowed size. |
| `WGL422047` | The file uploaded as the `icon` is not a PNG, JPG, or WebP. |
| `WGL400072` | The `consoleHomeUrl` was malformed, or it pointed to the console host. |

## 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. Update and partial update must also send the `X-Weegloo-Version` header (the current resource's `sys.version`) for optimistic concurrency control. Create and delete do not have this header.

```api-endpoint
{
  "title": "Read a single Organization",
  "method": "GET",
  "path": "/organizations/{organizationId}",
  "description": "Reads one Organization by sys.id.",
  "responseStatus": 200,
  "baseUrl": "https://cma.weegloo.com/v1",
  "pathParameterSchema": {
    "organizationId": { "type": "string", "description": "The sys.id of the Organization", "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": "ilLRJxDp",
      "type": "Organization",
      "createdBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
      "createdAt": "2026-05-11T10:51:16.832Z",
      "updatedBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
      "updatedAt": "2026-05-11T10:51:16.832Z",
      "version": 1,
      "isOfficial": false,
      "plan": { "sys": { "id": "free", "type": "Refer", "targetType": "Plan" } }
    },
    "name": "DailyWear Company",
    "description": "Company running an online clothing and accessories store"
  }
}
```

```api-endpoint
{
  "title": "Create Organization",
  "method": "POST",
  "path": "/organizations",
  "description": "Creates a new Organization. The body holds name and the optional description. Each plan has a limit on how many Organizations you can create, and exceeding the limit responds with an error.",
  "responseStatus": 201,
  "baseUrl": "https://cma.weegloo.com/v1",
  "pathParameterSchema": {},
  "requestHeaderSchema": {
    "Authorization": { "type": "string", "description": "Bearer token (CMA authentication)" }
  },
  "requestBodySchema": {
    "type": "object",
    "required": ["name"],
    "properties": {
      "name": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The Organization name (1-64 characters)" },
      "description": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The Organization description (1-128 characters, optional)" }
    },
    "example": {
      "name": "DailyWear Company",
      "description": "Company that runs the clothing store"
    }
  },
  "responseExample": {
    "sys": {
      "id": "3trmXRM3RqbgSnifyg7PVorg01Ex",
      "type": "Organization",
      "createdBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
      "createdAt": "2026-06-18T11:05:00.000Z",
      "updatedBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
      "updatedAt": "2026-06-18T11:05:00.000Z",
      "version": 1,
      "isOfficial": false,
      "plan": { "sys": { "id": "free", "type": "Refer", "targetType": "Plan" } }
    },
    "name": "DailyWear Company",
    "description": "Company that runs the clothing store"
  }
}
```

```api-endpoint
{
  "title": "Update Organization",
  "method": "PUT",
  "path": "/organizations/{organizationId}",
  "description": "Updates the Organization's name, description, icon, and consoleHomeUrl. This replaces the whole resource, so an omitted consoleHomeUrl clears the stored URL. 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 }
  },
  "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": ["name"],
    "properties": {
      "name": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The Organization name (1-64 characters)" },
      "description": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The Organization description (1-128 characters)" },
      "icon": { "type": "object", "description": "The Organization icon. A reference to an uploaded file's Upload", "properties": { "upload": { "type": "object", "description": "A Refer to an Upload obtained from the Upload API", "properties": { "sys": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "targetType": { "type": "string" } } } } } } },
      "consoleHomeUrl": { "type": "string", "format": "uri", "description": "The page shown in place of the default home screen in every Space under this Organization. An https URL that does not point to the console host. Omit it to clear the stored URL" }
    },
    "example": {
      "name": "DailyWear Company",
      "description": "Company running an online clothing, accessories, and footwear store",
      "consoleHomeUrl": "https://guide.dailywear.example"
    }
  },
  "responseExample": {
    "sys": {
      "id": "ilLRJxDp",
      "type": "Organization",
      "createdBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
      "createdAt": "2026-05-11T10:51:16.832Z",
      "updatedBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
      "updatedAt": "2026-06-18T11:06:00.000Z",
      "version": 2,
      "isOfficial": false,
      "plan": { "sys": { "id": "free", "type": "Refer", "targetType": "Plan" } }
    },
    "name": "DailyWear Company",
    "description": "Company running an online clothing, accessories, and footwear store",
    "consoleHomeUrl": "https://guide.dailywear.example"
  }
}
```

```api-endpoint
{
  "title": "Partially update Organization (JSON Patch)",
  "method": "PATCH",
  "path": "/organizations/{organizationId}",
  "description": "Updates only part of an Organization using 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 }
  },
  "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: /description" },
        "value": { "description": "The value used by add/replace/test" },
        "from": { "type": "string", "description": "The source location for move/copy" }
      }
    },
    "example": [
      { "op": "replace", "path": "/description", "value": "Company running an online clothing and accessories store" }
    ]
  },
  "responseExample": {
    "sys": {
      "id": "ilLRJxDp",
      "type": "Organization",
      "createdBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
      "createdAt": "2026-05-11T10:51:16.832Z",
      "updatedBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
      "updatedAt": "2026-06-18T11:07:00.000Z",
      "version": 3,
      "isOfficial": false,
      "plan": { "sys": { "id": "free", "type": "Refer", "targetType": "Plan" } }
    },
    "name": "DailyWear Company",
    "description": "Company running an online clothing and accessories store"
  }
}
```

```api-endpoint
{
  "title": "Delete Organization",
  "method": "DELETE",
  "path": "/organizations/{organizationId}",
  "description": "Deletes an 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 }
  },
  "requestHeaderSchema": {
    "Authorization": { "type": "string", "description": "Bearer token (CMA authentication)" }
  }
}
```

## Related documents {#related-documents}

- [Space](/api/reference/cma/space.md): The *Space*s under this *Organization*.
- [Organization Membership](/api/reference/cma/organization-membership.md): *Organization* members and reading the organizations you belong to.