Project Service

What is a Project?

A Project is the logically-isolated instance of Oystehr that segments your data from other Projects. Projects are completely independent from each other, having their own separate FHIR store, Applications, Users, etc. No Project can access data from another Project.

You should use a single Project for all of your production data. For example, if you have a patient portal, and a provider-facing EHR, a single Project should be used for both. You might also have a separate Project for development and testing environments.

Of the Actors in Oystehr, Users and M2M Clients exist inside a single Project, so they are invisible to other Projects and they can only interact with data inside the same Project. Developers are the only people who can belong to and act across multiple Projects, because they exist above the Project level. The Developers guide covers this in more detail.

Using the Project Service

The Project Service allows for configuration of project-wide settings. This simple service is best understood by example so let's take a look at how you can fetch your Project's settings.

Fetch your Project Settings with the SDK
  ZAPEHR_ACCESS_TOKEN: "<your_access_token>",
const project = await zapehr.project.project.get();

The response body looks like this:

  "id": "fd9b1113-4bd2-4dad-8631-a95ba035dfda",
  "name": "SANDBOX",
  "description": "Sandbox Project for trying out Oystehr",
  "signupEnabled": false,
  "defaultPatientRole": {
    "id": "31fcd69e-1b6b-41f1-a7b5-a1a20d976a89",
    "name": "Patient"
  "defaultSSOUserRole": {
    "id": "5167feba-7727-4d1c-8f2f-3493a61a1694",
    "name": "FrontDesk"
  "fhirVersion": "r4"
  • id — The unique identifier for your Project.
  • name — An internal-facing name for your Project.
  • description — An internal-facing description of your Project. Set it to something that will explain to Developers what this Project is for.
  • signupEnabled — Whether or not Users can self-register for Applications which use the Email + Password authentication method. This is set to false by default.
  • defaultPatientRole — This is the Role granted to Users who self-register with the Email + Password and Passwordless SMS authentication methods.
  • defaultSSOUserRole — This is the Role granted to Users who self-register with the Single Sign-On authentication method.
  • fhirVersion — The version of FHIR used by your Project, selected once when you create your Project. This cannot be changed after creation. Learn more about FHIR versions.

signupEnabled, defaultPatientRole, and defaultSSOUserRole are all covered in more detail in the Applications Self-Registration guide.

You can update your Project's settings with any of: