Users are the people who log into the Applications you configure for securing the apps you build on top of Oystehr. Consider some examples of Users:

  • A patient who logs into a patient portal app to schedule appointments and view lab results.
  • A doctor who logs into an EHR system to view patient records and write prescriptions.
  • A medical billing specialist who logs into an EHR system to review and resubmit rejected insurance claims.

Users log into Applications with one of a few authentication methods, as configured on the Application.

Every User has a FHIR Profile which represents them in the FHIR data model, either as a Practitioner or Patient.

By default, the way that Users are created in your Project is by inviting them with the Invite User endpoint. This is simple to use and ideal for many use-cases. Oystehr also supports self-registration for use-cases where you want Users to be able to create an account without an invitation, for example while self-scheduling their first appointment.

Note that there is a difference between Users and Developers. Users are the people who log into the applications you build. Developers are the people who build the apps that Users log into and use. Learn more about the difference between Developers and Users.

User Invites and Invitation Emails

To invite an email + password User to your Project, you make an Invite User (opens in a new tab) API request.

Invite a User with the SDK
  ZAPEHR_ACCESS_TOKEN: "<your_access_token>",
const user = await zapehr.project.user.invite({
  email: '[email protected]',
  applicationId: '36b974ef-e470-4f1b-9ceb-ccaf23b673bf',
  accessPolicy: {
    rule: [
        resource: ['*'],
        action: ['*'],
        effect: 'Allow',
  resource: {
    resourceType: 'Practitioner',

The response body includes an invitationUrl property:

  "id": "b4f1411f-bb12-4e8b-ad7b-f3475ad642cc",
  "name": "Jon Snow",
  "email": "[email protected]",
  "profile": "Practitioner/b351faef-d81d-4a33-11a9-2e31bd54807e",
  "accessPolicy": {
    "rule": [
        "resource": "*",
        "action": ["*"],
        "effect": "Allow"
  "roles": [],
  "invitationUrl": ""

Opening the invitationUrl in a browser will allow the invited user to set their password and log into the account. Your application should send this URL to the invited user in some way, typically via email with an API-friendly transactional email service.

As a convenience, Oystehr can automatically send an email with the invitationUrl to the invited User. You can enable this by setting shouldSendInviteEmail to true. The email sent by Oystehr contains no branding and nothing more than the link. It is intended for testing purposes only, and is not customizable.

Additional Resources