Skip to main content

Project vs Server Scoped Users

Server Scoped Users​

Server scoped Users can be used across multiple projects across the Medplum Server. Server scoped Users should be used for developers and administrators that need to interact with multiple projects (e.g. staging and production). By default, Practitioners are scoped to server.

Project Scoped Users​

Project scoped Users exist inside a single Project. Project scoped Users should be used for real practicing clinicians and patients that will primarily interact with a single production project. By default, Patients are scoped to project. If you want to include a project scoped User in multiple projects, you will need to invite them to each Project separately.

You can specify the scope of a User by adding the scope parameter to the Invite User endpoint.

const response = await medplum.post('/admin/projects/:projectId/invite', {
  resourceType: 'Practitioner',
  firstName: 'Test',
  lastName: 'User',
  email: 'test@example.com',
  scope: 'project' // or 'server'
})
info

For hosted customers, you will only have control over the User resources for your project scoped users. Self-hosted customers can access server scoped users from their super admin project.

note

If you want to create a custom email flow for your Practitioners, they will need to be invited as a Project Scoped Users so that the UserSecurityRequest resources are also scoped to the project.

Changing the Name and Email of a Project-Scoped User​

Project Admins have the ability to update the name and email address of project-scoped users directly from the Medplum Admin App or via the API. This is in contrast to server-scoped users, whose details can only be changed by Super Admins.

info

To change the email address that is displayed in the Medplum app (and in FHIR resources), you must update both the User resource and the user's Profile resource (such as Patient or Practitioner). The User resource controls login and authentication, while the Profile resource controls the display name and email shown in clinical and administrative contexts.

Recommended approach: Use the $update-email operation which automatically handles updating both resources in a single transaction.

How to update a User's login email:

  • Medplum Admin App (Project Scoped Users Only):
    Navigate to the Project Admin page, select the "Users" tab, and click on the user you wish to edit. You can update their email address directly from the user details page.

  • API (Recommended - FHIR $update-email operation):
    The $update-email operation is the recommended method as it automatically updates both the User resource and the profile resource in a single transaction:

    await medplum.post(`fhir/R4/User/${userId}/$update-email`, {
      resourceType: 'Parameters',
      parameter: [
        { name: 'email', valueString: 'new-email@example.com' },
        { name: 'updateProfileTelecom', valueBoolean: true },
        { name: 'skipEmailVerification', valueBoolean: true }
      ]
    });
    note

    For server scoped users, where you don't have access to the User resource, you can get the user id from the ProjectMembership resource's ProjectMembership.user reference.

    const memberships = await medplum.searchResources('ProjectMembership', {
      profile: profileReference
    });

    const userId = memberships[0].user?.reference?.split('/')[1];

    await medplum.post(`fhir/R4/User/${userId}/$update-email`, {
      resourceType: 'Parameters',
      parameter: [
        { name: 'email', valueString: 'new-email@example.com' },
        { name: 'updateProfileTelecom', valueBoolean: true },
        { name: 'skipEmailVerification', valueBoolean: true }
      ]
    });

  • API (SCIM):
    Project Admins can also update a user's email using the SCIM API:

    curl -X PATCH 'https://api.medplum.com/scim/v2/Users/{userId}' \
      -H 'Authorization: Bearer {accessToken}' \
      -H 'Content-Type: application/json' \
      -d '{
        "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
        "Operations": [{
          "op": "replace",
          "path": "emails[type eq \"work\"].value",
          "value": "new-email@example.com"
        }]
      }'