### Server Scoped Users

Server scoped [`Users`](/content/docs/api/fhir/medplum/user/index.html) 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`](/content/docs/api/fhir/medplum/user/index.html) exist inside a single [`Project`](/content/docs/api/fhir/medplum/project/index.html). 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`](/content/docs/api/fhir/medplum/project/index.html) separately.

You can specify the scope of a [User](/content/docs/api/fhir/medplum/user/index.html) by adding the `scope` parameter to the [Invite User](/content/docs/api/project-admin/invite/index.html) endpoint.

```ts
const response = await medplum.post('/admin/projects/:projectId/invite', {

resourceType: 'Practitioner',

firstName: 'Test',

lastName: 'User',

email: 'test@example.com',

scope: 'project' // or 'server'

})
```

Production Project

| Project                      | Membership                     |
|-----------------------------|-------------------------------|
| Production Project          | **Company Dev/Admin** _Server Scoped_  |
| Staging Project             | **Test Doctor 1** _Project Scoped_  |
| Staging Project             | **Example Patient 1** _Project Scoped_  |
| Staging Project             | **John Doe** _Project Scoped_  |
| Production Project          | **Dr. Alice Smith** _Project Scoped_  |

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](/content/docs/self-hosting/super-admin-guide/index.html).

**Recommended approach:** Use the [`$update-email`](/content/docs/api/fhir/operations/user-update-email/index.html) operation which automatically handles updating both resources in a single transaction.

## 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.

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.

- **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):**

```typescript
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 }

]

});
```

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.

```typescript
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:

```bash
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"

}]

}'
```