Authentication & Authorization

Overview

The MediSync API uses JWT (JSON Web Token) authentication to secure all protected endpoints. The same token authenticates the Dashboard (REST) API and the Speech (WebSocket) API. This guide covers registration, login, and how to use and manage tokens.

Authentication flow

Create a MediSync account with your professional credentials.

Authenticate with email and password to receive a JWT token.

Use the token

Send the JWT as a Bearer token in the Authorization header on every protected request.

Tokens can be renewed without re-entering credentials — call POST /api/refresh-token with a still-valid token. See Token management.

Registration

curl -X POST https://app.medisync.me/api/register \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Dr.",
    "firstName": "John",
    "lastName": "Doe",
    "email": "doctor@example.com",
    "password": "your_password",
    "specialty": "Cardiology",
    "ehr_system_type": "Epic",
    "ehr_system_name": "Epic MyChart"
  }'

Response (201 Created):

{
  "success": true,
  "result": {
    "_id": "6578a1b2c3d4e5f601234567",
    "title": "Dr.",
    "firstName": "John",
    "lastName": "Doe",
    "email": "doctor@example.com",
    "specialty": "Cardiology",
    "ehr_system_type": "Epic",
    "ehr_system_name": "Epic MyChart",
    "isVerified": false
  }
}

New accounts are created unverified and a verification email is sent. Email verification is enforced at login — an unverified account cannot log in (see the error responses below).

Fields

firstName (required)
lastName (required)
email (required, must be unique)
password (required, minimum 6 characters)
specialty (required)
ehr_system_type (required) — EHR system category
ehr_system_name (required) — specific EHR system name
title (optional) — medical title (Dr., Prof.)

Password requirements

Minimum 6 characters. Use a long, unique password — these accounts hold patient data, and a password manager is strongly recommended.

Registration errors:

{
  "error": "Diese E-Mail-Adresse ist bereits registriert."
}

{
  "error": "Bitte geben Sie ein Passwort mit mindestens 6 Zeichen ein."
}

Authenticate with your credentials to obtain a JWT token:

curl -X POST https://app.medisync.me/api/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "doctor@example.com",
    "password": "your_password",
    "remember": false
  }'

Success response (200 OK):

{
  "success": true,
  "token": "<JWT>",
  "uid": "6578a1b2c3d4e5f601234567",
  "userTitle": "Dr.",
  "firstName": "John",
  "lastName": "Doe",
  "twoFactorEnabled": false
}

Parameter	Type	Required	Description
`email`	string	Yes	Registered email address
`password`	string	Yes	Account password
`remember`	boolean	No	Issue a longer-lived token instead of a standard one (default `false`)
`twoFactorCode`	string	No	TOTP or backup code, for accounts with 2FA enabled

Two-factor authentication

If an account has 2FA enabled and twoFactorCode is omitted, login returns 202 Accepted with a challenge — resubmit with the twoFactorCode included.

{
  "success": true,
  "requires2FA": true,
  "message": "Bitte geben Sie Ihren 2FA-Code ein."
}

Platform messages are returned in German, and authentication failures use a failed label alongside error.

{
  "failed": "Unauthorized Access",
  "error": "Ungültige E-Mail oder Passwort."
}

{
  "failed": "Email Not Verified",
  "error": "Bitte bestätigen Sie Ihre E-Mail-Adresse, bevor Sie sich anmelden.",
  "needsVerification": true
}

{
  "error": "Zu viele Anmeldeversuche. Bitte versuchen Sie es später erneut.",
  "rateLimited": true
}

Using JWT tokens

Include your token in the Authorization header for all protected endpoints:

Authorization: Bearer YOUR_JWT_TOKEN

Example request

curl -X GET https://app.medisync.me/api/user/profile \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Token structure

Treat the token as opaque. Do not decode it, parse it, or depend on its internal structure — the claims it carries are an internal detail and change without notice. The server extracts your user id from the token, so no separate uid parameter is ever required.Everything you need about a token is available through the API: the authenticated user from GET /api/user/profile, and expiry by handling 401 and refreshing.

Authorization

User identification

User identification is handled entirely through the JWT. The server extracts the user id from the token to authenticate the request and scope data access — you never pass a user id explicitly.

Data access control

Doctors can access only their own resources (their appointments, recordings, transcriptions, notes, and documents). Accessing another user’s resource returns 403 Forbidden.
Admin roles have elevated, system-level access (special permissions).

Subscription requirements

Some actions require an active subscription or trial — notably creating appointments and AI note generation. If your trial or subscription has lapsed, POST /api/appointments/add returns 403 with a German message. Check your subscription status in the dashboard.

Error handling

Error responses are JSON, but the shape depends on the layer that produced them:

Auth middleware (missing/invalid/revoked token) uses a message field.
Route handlers (validation, not-found, ownership) use an error field.

{
  "success": false,
  "message": "Unauthorized"
}

{
  "success": false,
  "message": "Session ended on this device because you signed in elsewhere.",
  "code": "SESSION_REVOKED"
}

{
  "success": false,
  "error": "Forbidden"
}

The API does not return the invented, English error code values shown in some older examples (e.g. AUTH_REQUIRED). Branch on the HTTP status code and the presence of message / error / code fields shown above.

Token management

Expiration

Tokens expire. A standard token is scoped to the working day; remember: true issues a longer-lived one. Exact lifetimes are an internal detail and change — do not hard-code an expiry or compute one from the token. Treat a 401 as the signal to refresh or re-authenticate.

Refreshing a token

POST /api/refresh-token slides the current device’s session forward and returns a new token. It requires a still-valid token, so refresh before expiry rather than after — it extends a live session and cannot revive an expired one.

curl -X POST https://app.medisync.me/api/refresh-token \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

{
  "success": true,
  "token": "<JWT>"
}

Call this at the start of any long-running operation — a recording that outlives its token would otherwise fail to save — and periodically during long ones.

If a token has already expired, there is nothing to refresh: call POST /api/login again.

Signing out

POST /api/logout ends the current device’s session. Other devices stay signed in, and the token used for the call stops working on its next request.

curl -X POST https://app.medisync.me/api/logout \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Managing devices

An account can be signed in on several devices at once, up to a fixed cap. Signing in beyond it evicts the least-recently-active device.

Endpoint	Effect
`GET /api/sessions`	List the account’s active devices
`DELETE /api/sessions/{id}`	Revoke one device by its session `id`
`DELETE /api/sessions`	Sign out every device except the current one

GET /api/sessions returns one entry per device with an id, a human-readable device_label, platform, last_seen_at, created_at, and current (whether it is the calling device). Devices are addressed by that id; the underlying session identifiers are never exposed.

{
  "success": true,
  "data": [
    {
      "id": "66b1c0de9a7f4e0012ab34cd",
      "device_label": "Chrome · Windows",
      "platform": "web",
      "last_seen_at": "2026-07-15T13:20:00.000Z",
      "created_at": "2026-07-14T08:02:00.000Z",
      "current": true
    }
  ]
}

This is the path to follow if a token is lost or a device is compromised: revoke that device, or DELETE /api/sessions to cut everything except the one you’re on. Revocation takes effect on the device’s next request.

Handling expired or revoked tokens

When you receive a 401:

If the token is merely expired and you still hold a valid one, call POST /api/refresh-token. Otherwise re-authenticate with POST /api/login.
Retry the original request with the new token.

A 401 carrying code: "SESSION_REVOKED" means that specific device’s session ended — through logout, an explicit revocation, or eviction past the device cap. Treat it as a sign-out and send the user back to login rather than retrying.

Security best practices

A MediSync token grants full access to a doctor’s patient data for its whole lifetime. Handle it accordingly.

Token storage

Browser: keep the token in memory, or in a Secure, HttpOnly, SameSite cookie set by your own backend. Avoid localStorage and sessionStorage — any XSS on your page can read them.
Mobile: use the platform keystore (iOS Keychain, Android Keystore), not plain preferences files.
Server-side: keep it in process memory or a secrets manager; never in source control or a build artifact.
Call POST /api/logout on sign-out and discard the token.

Network security

Always use HTTPS / WSS, and validate TLS certificates.
Keep tokens out of your own logs, analytics, and error reports.
Refresh proactively rather than letting tokens sit long-lived in client storage.
Use GET /api/sessions to surface active devices to the user, and revoke anything unexpected.

Tokens in URLs. As a rule, keep the token in the Authorization header and out of request URLs — URLs end up in browser history, Referer headers, proxy access logs, and error-tracking tools.The one exception is the Speech API, where the token is a token query parameter because browser WebSocket clients cannot set custom headers. That connection is WSS-only, and MediSync does not log the query string on its side. On yours: never log or persist the connection URL, build it immediately before opening the socket, and keep it out of any string you hand to logging or monitoring.

Rate limiting

Rate limits apply across the MediSync API. Limited responses return 429 with standard RateLimit-* headers and Retry-After. Treat any 429 as retryable: back off for the interval the response indicates rather than retrying immediately, and build clients so a limit is handled gracefully wherever it appears.

Getting Started

API Reference

Authentication

User

Appointments

Recordings

Transcriptions

Notes

Documents

Authentication & Authorization

Overview

Authentication flow

Registration

Two-factor authentication

Using JWT tokens

Example request

Token structure

Authorization

User identification

Data access control

Subscription requirements

Error handling

Token management

Expiration

Refreshing a token

Signing out

Managing devices

Handling expired or revoked tokens

Security best practices

Token storage

Network security

Rate limiting

Next steps

API Reference

Login endpoint

Reporting a vulnerability

​Overview

​Authentication flow

​Registration

​Login

​Login parameters

​Two-factor authentication

​Login errors

​Using JWT tokens

​Example request

​Token structure

​Authorization

​User identification

​Data access control

​Subscription requirements

​Error handling

​Token management

​Expiration

​Refreshing a token

​Signing out

​Managing devices

​Handling expired or revoked tokens

​Security best practices

Token storage

Network security

​Rate limiting

​Next steps

API Reference

Login endpoint

Reporting a vulnerability

Overview

Authentication flow

Registration

Login

Login parameters

Two-factor authentication

Login errors

Using JWT tokens

Example request

Token structure

Authorization

User identification

Data access control

Subscription requirements

Error handling

Token management

Expiration

Refreshing a token

Signing out

Managing devices

Handling expired or revoked tokens

Security best practices

Rate limiting

Next steps