Spaces and Organizations

What they are and how they differ

At Contentful, we want to allow our customers to manage their users in a way that truly reflects real-world needs, and especially for sizable companies, granularity is an important requirement. This is why Contentful introduces the distinction between spaces and organizations: together with roles and permissions, we believe that they provide the right tools for effective user management. Let's take a look!

What are spaces and organizations?

From the simplest perspective spaces house content types, entries, and assets. Practically speaking, however, it is more useful to think of a space as serving a particular purpose. It is not only a collection of content, it’s a collection of content with a certain goal. A space might contain content for a new marketing campaign, for a homepage, for a PIM system, or for anything else.

Since different spaces have different goals, each can be configured individually. Some familiar settings include:

  • Webhooks
  • API keys
  • Locales
  • Content preview
  • Space roles

For instance: you might not want to have the same locales on your homepage as in your PIM system, or you might want to assign specific users the right to create entries of a specific content type.

Organizations stand above spaces and contain them. Moreover, spaces are deleted and created from the organization level. A common setup we see is for an organization to have some spaces for development (or even for playing around with a few ideas), and others for production projects where editors usually do their work.

Generally speaking, organizations are for administration. This means of course managing spaces, but also handling monetary matters as well. In particular:

  • You can change your current Contentful plan (e.g. go from medium to large).
  • You can define your billing information.

Although organizations and spaces differ in some clear and important ways, they also share two important things:

  • Users belong to them.
  • All users that belong to them have roles.

This means that there are two sorts of roles and two sorts of membership: one for spaces and another for organizations.

In the case of membership, organization membership is required for space membership. Why so? Recall that organizations are for administration and spaces are for working on a particular project. The answer, then: you must be part of the administrative entity before getting to work.

Belonging to a space

The previous section distinguished between different sorts of roles and membership: one on the space level and another for organizations. Now to get into the nitty gritty about space roles. While it's not possible to list all space roles here, as enterprise plans come with the ability to customize them. Overall, we can classify them in two groups: space admin, and everything else. Space admins alone have the ability to do three things:

  • Modify users’ space roles.
  • Modify the available roles in the space.
  • Delete any space they administer.

In order to accomplish any of these three feats, users must be space admins. The following table makes this clear:

Space role Can see Can modify Can remove
Non-admin custom custom custom
Admin everything + each user's space roles, available space roles + the space itself

Belonging to an organization

Organization membership is required for space membership. In order to belong to a space, you must belong to the organization containing that space. There are three fixed organization roles: owner, admin, and member. Unlike space roles, organization roles cannot be customized.

As long as there’s at least one organization owner, you can distribute the roles however you please. Let’s say, for example, you have 10 users in your organization. You may have 1 owner and 9 members; 2 owners, 3 admins and 5 members; or even 10 owners.

As for what each of these organization roles can do, it's summarized in the following table:

Organization role Can see Can modify Can remove
Member spaces they belong to content (space roles permitting) content (space roles permitting)
Admin + subscription details + organization memberships + organization memberships
Owner + billing details + other organization owners + subscriptions

While spaces only have one level of administration (space admin), organizations have two levels: organization admin and organization owner. Organization admins can take care of all the day-to-day matters including memberships and roles for both spaces and organizations. Organization owners can do everything organization admins can do, but owners also have the ability to take care of the uncommon but necessary tasks, such as modifying billing details, changing subscriptions, and appointing additional owners.

What, then, about organization members? They have no administrative powers. All an organization member can do is interact with content. An organization member’s rights, then, are really given by their space role.

Fold together: considering both kinds of roles

A major message from the above is that each user has two roles! There are space roles and, separately, organization roles. Space roles, again, dictate how a user can interact with content in a given space and organization roles define a user’s rights at the higher, organizational level.

One might expect that space and organization roles are correlated: if a user has more privileges in a space (e.g. is a space admin) then that user will have more privileges in an organization (e.g. is an organization owner) — or vice versa. Although this can be the case, there are often good reasons to separate the roles.

Take, for instance, a case in which someone is responsible for billing matters but will not interact with content. In this case it would be reasonable for them to be an organization owner (so as to modify billing information) but to have a space role with few privileges, if they are even to belong to a space at all.

Also consider a user who is totally in charge of a marketing website but should not have access to subscription information. This user should be a space admin for the marketing website’s space but a simple member at the organization level.

Sometimes the combination of space and organization roles can be confusing. Say, for instance, you are an organization member but a space admin like in the above case. As an organization member, you do not have the right to invite users to the organization. As a space admin, you do have the right to invite users to the space. With these roles, you may invite somebody to your space only if they already belong to the organization; if they do not belong to the organization, you cannot invite them to your space.

Takeaways

Contentful comes with spaces and organizations. Spaces are where you interact with your content for your particular goals; organizations are where you administer your spaces. Each user has two different kinds of roles: one for spaces and another for organizations. These different kinds of roles have different purposes and one should be careful to consider both. For more on the topic of managing spaces programmatically, you can read about treating your CMS as code.

Discover more Contentful.

If you enjoyed this article, you might like our product as well.

What our product does

Take a look at the API capabilities, delivery infrastructure and friendly editing environment.
See features

What our clients built

From apps and sites to digital signage and iBeacon campaigns — we deliver content everywhere.
See real-life examples