Your Account and Organization

Heads up — this page will change. Account creation and organization management will move to console.esus.health, which is currently in development. The concepts described here (users, organizations, multi-tenant isolation) stay the same; only the self-service UI and onboarding flow will change. We will update this page when the console ships.

When you register with ESUS, you create two things: a User Account and an Organization. Understanding this distinction is key to building multi-tenant healthcare applications.

What is an Organization

An Organization in ESUS represents your health entity - a hospital, clinic, laboratory, or application developer. All FHIR resources belong to an organization, ensuring complete data isolation between tenants.

Organizations use Row-Level Security (RLS) in PostgreSQL, which means you can never accidentally access another organization’s data.

Creating Your Organization

When you register, your organization is created automatically:

curl -X POST https://api.esus.health/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@hospital.com",
    "password": "SecurePass123!",
    "firstName": "Admin",
    "lastName": "User",
    "organizationName": "City General Hospital"
  }'

Response (HTTP 202 Accepted):

{
  "message": "Verification email sent. Please check your inbox to activate your account."
}

Registration is asynchronous: the organization is provisioned, and a verification link is sent to the email you provided. You log in after verifying the email — see the next page on Authentication for the login flow.

User Roles

Roles are scoped to the organization. Every user has an organizational role and may have additional custom roles defined by administrators within the organization.

Role	Scope	Meaning
`owner`	Organization	Created the organization or was promoted. Full access, including billing, member management, and API keys.
`member`	Organization	Invited user. Access is determined by the custom roles assigned in the organization.
Custom roles	Organization-defined	Fine-grained roles with specific FHIR resource/action permissions (RBAC + ABAC).

Custom roles let administrators model real-world clinical roles (clinician, nurse, biller, etc.) and bind them to the exact permissions each role needs.

Inviting Team Members

Owners can invite team members to join the organization:

curl -X POST https://api.esus.health/auth/invite \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "doctor@hospital.com",
    "role": "member"
  }'

Response (HTTP 201 Created):

{
  "message": "Invitation sent.",
  "invitationId": "c1a2e3d4-5b6f-7890-abcd-ef1234567890"
}

The invitee receives an email with a link to accept the invitation and complete their profile.

Next Steps

With your account and organization set up, learn how to authenticate with the API.