Groups
This document will help you create groups and organisations, manager their members and accept or reject invites.
AI assisted, human approved — novem uses AI to review and keep our documentation up to date.
Novem allows you to create and be part of groups and organisations. This is the principle entity for access management on the novem platform and how various documents and visualisations are shared between users.
In this document we will show you:
- How to create a new group and invite a user
- How to promote the user to an admin role
- How to remove a user
- How to accept an invite from another user
- How to create a group page
When it comes to access management and sharing novem has the concept of groups.
Groups can either belong to a user and be a user group or
an organisation and be an org group
A user group consists of an @ followed by a username, then a ~ and a group name. An organisation group consists of a + followed by an organisation name, then a ~ and a group name.
Neither usernames, organisation names or groupnames may contain a space.
User groups are created by PUTing a group name under the /admin/groups/ folder and
organisations by PUTing an organisation name under the /admin/orgs/ folder.
To add a user to a group you simply PUT the username in the
/admin/groups/<group_name>/roles/<ROLE>/ folder where <ROLE> is one of
founders, admins, superusers or members.
The user creating a group or organisation is automatically given the founder role.
The groups of which you are a member are listed under /admin/groups, keyed by
their group slug (not the display name). Org groups you can see are also
surfaced under /orgs/<org>/groups.
User groups are the unit of sharing for individuals. Create one by PUTting a
group name under your /admin/groups/ folder; you become its founder
automatically.
PUT /v1/admin/groups/analysts
A user group is referenced elsewhere, for example when sharing a visual, as
@username~groupname (e.g. @alice~analysts).
Add a member by PUTting their username into one of the group's role folders.
The roles, from most to least privileged, are founders, admins,
superusers and members.
PUT /v1/admin/groups/analysts/roles/members/bob
The invited user receives an invitation they must accept before the membership
becomes active; until then they show in the role listing with an I- prefix
(the same pending marker used for social connections).
Pending invites are listed under the invited user's /admin/invites/ folder,
keyed by the group reference (@alice~analysts). Each invite holds a single
accept endpoint; POST yes to it to accept, or no to decline:
GET /v1/admin/invites -- list pending invites
POST /v1/admin/invites/@alice~analysts/accept -- body: yes (or no to decline)
curl -X POST -H "Authorization: Bearer $NOVEM_TOKEN" \
-H "Content-Type: text/plain" \
--data "yes" \
https://api.novem.io/v1/admin/invites/@alice~analysts/accept
Note: Text bodies must be sent as text/plain. curl's --data flag
defaults to application/x-www-form-urlencoded, which the API rejects —
always pass -H "Content-Type: text/plain" alongside it.
Changing a member's role is the same PUT, into a different role folder — to
promote bob from member to admin:
PUT /v1/admin/groups/analysts/roles/admins/bob
DELETE the user from the role folder to revoke their membership.
DELETE /v1/admin/groups/analysts/roles/members/bob
Organisations are shared parents for groups that belong to a company or team
rather than a single user. Create one by PUTting an organisation name under
/admin/orgs/; as with groups, the creator becomes the founder.
PUT /v1/admin/orgs/acme
Note: Two constraints apply, both enforced by the API: only
organisation accounts can create organisations (a regular account gets a
403), and each account can create exactly one.
Organisation-level roles (membership of the organisation itself) are managed
under /admin/orgs/<org>/roles/<role>/<user> using the same four role folders.
An organisation's groups live under the org and are referenced as
+orgname~groupname, e.g. +acme~research. They are created and have their
members managed exactly like user groups, one level deeper under the org:
# create the research group under the acme org
PUT /v1/admin/orgs/acme/groups/research
# add a member
PUT /v1/admin/orgs/acme/groups/research/roles/members/bob
A group or org has a profile, the page people see at its public URL. It works
like your own profile: a profile folder
with text fields and imagery, all written with POST (or PUT/DELETE for
imagery) by a founder or admin.
| Verb | Path | Description |
|---|---|---|
GET | .../profile | The profile folder |
POST / GET / DELETE | .../profile/name | Display name |
POST / GET / DELETE | .../profile/description | Description, rendered as markdown |
POST / GET / DELETE | .../profile/picture/image | Avatar |
POST / GET / DELETE | .../profile/picture/banner | Banner |
POST / GET / DELETE | .../profile/picture/mask | Avatar crop (x,y,r) |
.../ is /admin/groups/:group for a user group or
/admin/orgs/:org/groups/:group for an org group; orgs themselves expose the
same profile tree at /admin/orgs/:org.
The profile/options folder holds boolean toggles
(yes/no, default no), again founder/admin only:
| Option | Effect |
|---|---|
public | Whether the group/org page is reachable at all |
show_profile | Show the profile page |
show_description | Show the description on it |
show_members | Show the member list |
is_open | Let users join without an invite |
Note: for organisations and org groups the show_* options
require a premium subscription. User-group options are available on all
plans.
Groups and orgs also carry comment threads at
.../threads/*, on the same paid-to-write, free-to-read terms as the rest of
the platform.
Org themes (the branding applied to a whole organisation's content) are documented separately under org themes.
The management endpoints above live under /admin. The read-oriented views are
public (subject to the visibility options):
| Path | Description |
|---|---|
/v1/orgs | Organisations visible to you |
/v1/orgs/:org | An organisation — description and groups |
/v1/orgs/:org/groups | The org's groups |
/v1/orgs/:org/groups/:group | A group — name, description, profile, role (your role in it) and shared content |
/v1/users/:user/groups | A user's groups visible to you |
/v1/o/:org | The org FQNP alias — card, banner, img, and the org's visuals under p / g / m / d / v |