Magidoc

CMS Managed Users

#

This document describes how CMS platforms can programmatically manage user access to an organisation using the upsertUserByEmail and evictUserByEmail GraphQL mutations.

1. Overview

#

CMS platforms can manage which users have access to a Cloudshelf organisation by:

  • Adding new users - Create a user account and grant organisation access in a single operation
  • Granting access to existing users - If a user already exists, grant them access to the organisation
  • Updating user roles - Change the role of a user who already has access
  • Removing user access - Revoke a user's access to the organisation

2. Prerequisites

#

Authentication: Your API key must have the USERS MODIFY permission to use these mutations.

Roles: Before assigning users, ensure the organisation has at least one role configured. You can reference roles by either:

  • roleId - The global ID of the role
  • roleName - The name of the role (e.g., "Staff", "Manager")

If both are provided, roleId takes precedence.

3. Add or Update User Access

#

The upsertUserByEmail mutation handles three scenarios:

Scenario
Behaviour
User does not exist
Creates a new user account and grants organisation access
User exists, no org access
Grants the existing user access to the organisation
User exists, has org access
Updates the user's role

Input Fields:

Field
Type
Required
Description
emailAddress
String
Yes
The user's email address (used as the lookup key)
firstName
String
Yes
The user's first name (only used when creating a new user)
lastName
String
Yes
The user's last name (only used when creating a new user)
roleId
GlobalID
No*
The ID of the role to assign
roleName
String
No*
The name of the role to assign

*Either roleId or roleName must be provided.

Example Mutation:

Success Response:

Email Notifications:

  • When a new user is created, they receive a welcome email with a password reset link
  • When an existing user is granted access, they receive a notification email
  • Role updates do not trigger emails

4. Remove User Access

#

The evictUserByEmail mutation removes a user's access to the current organisation.

Important Notes:

  • Users cannot evict themselves
  • This only removes organisation access; the user account remains intact
  • Returns true on success, false on failure

Example Mutation:

Success Response:

5. Error Handling

#

The upsertUserByEmail mutation returns a userErrors array containing any errors that occurred.

Common Error Codes:

Code
Description
ENTITY_INVALID_FIELD
Invalid email address format
ENTITY_CREATION_MISSING_FIELD
Neither roleId nor roleName was provided
INVALID_ARGUMENT
The specified role was not found

Example Error Response:

For evictUserByEmail , the mutation returns false if:

  • The email address format is invalid
  • The user is attempting to evict themselves
  • The user does not have access to the organisation