Bring your team in

Everyone who writes has an account, and nobody has more access than their job needs.

Before you start

• You are an owner or an admin of the organization.

Steps

1. Open Members at /o/{orgId}/members and invite by email. An invitation names the role it grants.

2. Pick the role. There are seven, from most to least privileged:

   Role	What it can do
   Owner	Everything, including billing and deleting the organization.
   Admin	Settings, members, roles and spaces. Not billing.
   Maintainer	Writes and publishes documentation, and manages a space's structure.
   Editor	Writes and publishes in the content surfaces — blog, changelog, roadmap.
   Moderator	Moderates the community: flags, locks, moves, suspensions.
   Member	Takes part — posts, comments, votes.
   Guest	Read-only.

   There is no "Viewer". The read-only role is Guest. (An earlier version of this page named Viewer, listed four of the seven, and described Editor as the docs role; all three were wrong.)

3. Grant at the right scope. A role given at the organization applies everywhere; a role given on one space applies only there, and a space grant can narrow an organization grant as well as widen it. A deny always wins over an allow, at any level.

4. If you need something that is not one of the seven, build a custom role at /o/{orgId}/roles out of individual capabilities, and use groups at /o/{orgId}/groups to grant it to several people at once.

Granting a role to a whole group

Instead of granting a role person by person, grant it to a group. This needs org.manage_roles.

POST /orgs/{orgId}/group-grants
{
  "groupId": "<groupId>",
  "role": "MODERATOR",
  "spaceId": "<spaceId>",
  "effect": "ALLOW"
}

Leave spaceId out (or null) for an organization-wide grant; give it to confine the grant to one space. effect is ALLOW (the default) or DENY, and a deny always wins. customRoleId grants one of your custom roles instead of a built-in one. You cannot grant a role with capabilities you lack, and only an owner can grant ownership; both are 403. An unknown group or space is a 404. Create answers { "grant": ... }.

GET /orgs/{orgId}/group-grants lists grants and narrows with ?spaceId= and ?groupId=. DELETE /orgs/{orgId}/group-grants/{id} revokes one.

A member's group title and primary group

A member can choose how groups present them. A group (or a badge) may carry a title, and a member may adopt one of the titles they have been granted and pick which of their groups is their primary group, whose colour and flair render next to their name. Any signed-in member can do this for themselves; it needs only org.read.

GET /orgs/{orgId}/group-identity
# { "current": { "title", "primaryGroupId" },
#   "adoptableTitles": [ ... ], "primaryGroups": [ { "id", "name" } ] }

PUT /orgs/{orgId}/group-identity
{ "title": "Core team", "primaryGroupId": "<groupId>" }

Send null to clear either. A title the member has not been granted is a 422 ("That title is not one you have been granted"), and so is a primary group they do not belong to.

Asking what you may do in a space

GET /orgs/{orgId}/spaces/{spaceId}/my-access (needs space.read) answers { "canEdit": boolean, "canModerate": boolean } for the caller: whether they hold docs.write and forum.moderate there. Use it to decide whether to show an "Edit this page" or moderation control. A role does not imply the answer (a plain member can read a space but cannot edit it), so ask rather than guess from the role.

Requiring SSO

Connect your identity provider at /o/{orgId}/sso and turn on Require SSO there. After that, members sign in through your provider and a password is no longer an option.

That path is the one to use. There is no "Settings → Authentication" screen — the organization console has no authentication route at all. The three ways this was previously described sent people looking for a page that does not exist.

Reader sign-in is a different setting in a different place. SSO at /o/{orgId}/sso governs the people who write; who may read a space is configured separately — see Reader sign-in.

Where each control lives

How to know it worked

The invited person appears under Members with the role you chose, and their first sign-in lands in your organization rather than in a new one of their own.

If they land in an empty organization of their own, they signed up fresh instead of accepting the invitation — delete that organization and have them use the link in the email.

What's next

• Team and permissions — the capability model behind the roles, and how org and space grants resolve.

• SSO and authentication — setting up a provider.

In the API

Every operation below is also reachable from the other surfaces without a dedicated command. forumulate api <Operation> calls it from the CLI, the JavaScript SDK has a typed method for each one (the last column names it; the Python and Go clients are generated from the same spec), and an agent reaches the organization-scoped ones through the MCP call_api tool. Where a CLI command or MCP tool exists too, the last column names it. Operation names link to the API reference.

Badge Query Grant

Custom Role

Group Grant

Group Identity

Invite

Lti Deep Link

Member Merge

Member Segments

Public Identity

Rbac

Roles

Scim Admin

Sessions

Space my access