Authentication & Authorization

Overview

MediSync API uses JWT (JSON Web Token) authentication to secure all protected endpoints. This guide covers the complete authentication flow, token management, and authorization requirements.

Authentication Flow

User Registration

Create a new MediSync account with medical credentials

Authenticate with email and password to receive a JWT token

Token Usage

Include the JWT token in the Authorization header for all API requests

Token Refresh

Handle token expiration and refresh as needed

Registration

Create New Account

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": "SecurePassword123!",
    "specialty": "Cardiology",
    "ehr_system_type": "Epic",
    "ehr_system_name": "Epic MyChart"
  }'

Response:

{
  "success": true,
  "message": "User registered successfully. Please verify your email.",
  "user": {
    "id": "user_123456",
    "email": "doctor@example.com",
    "isVerified": false
  }
}

Email verification is required before using most API features. Check your email for the verification link.

Registration Requirements

Required Fields

title: Medical title (Dr., Prof., etc.)
firstName: First name
lastName: Last name
email: Professional email address (must be unique)
password: Secure password (min 8 characters)
specialty: Medical specialty
ehr_system_type: EHR system category
ehr_system_name: Specific EHR system name

Password Requirements

Minimum 8 characters
Mix of uppercase and lowercase letters
At least one number
Special characters recommended

Obtain JWT Token

Authenticate with your registered credentials:

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

Success Response:

{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiI2NTc4OWFiY2RlZjEyMzQ1Njc4OTAiLCJpYXQiOjE3MDMxMjM0NTYsImV4cCI6MTcwMzIwOTg1Nn0.example_signature",
  "uid": "user_123456",
  "userTitle": "Dr.",
  "firstName": "John",
  "lastName": "Doe"
}

Error Response:

{
  "success": false,
  "error": "Invalid email or password"
}

Parameter	Type	Required	Description
`email`	string	Yes	Registered email address
`password`	string	Yes	Account password
`remember`	boolean	No	Extended session duration

Using JWT Tokens

Authorization Header

Include your JWT token in the Authorization header for all protected API calls:

Authorization: Bearer YOUR_JWT_TOKEN

Example API Request

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

Token Structure

MediSync JWT tokens contain:

{
  "header": {
    "alg": "HS256",
    "typ": "JWT"
  },
  "payload": {
    "userId": "user_123456",
    "iat": 1703123456,
    "exp": 1703209856
  }
}

Authorization Levels

User Identification

User identification is automatically handled through the JWT token. The server extracts the user ID from the token’s payload and uses it to:

Authenticate the requesting user
Authorize access to protected resources
Ensure users can only access their own data

No separate uid parameter is required in API requests. The JWT token contains all necessary user identification information.

Subscription Requirements

Certain endpoints require an active subscription:

Appointment Creation: Creating new appointments
AI Features: Clinical note generation, diagnosis prediction
Advanced Analytics: Detailed reporting and insights

Check subscription status:

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

Data Access Control

Users can only access their own data:

Doctors: Access only their own patients and appointments
Patients: Access only their own medical records
Admin: System-wide access (special permissions)

Error Handling

Authentication Errors

401 Unauthorized

Common causes:

Missing Authorization header
Invalid JWT token format
Expired token
Revoked token

Solution: Re-authenticate to get a new token

403 Forbidden

Common causes:

Valid token but insufficient permissions
Subscription required but not active
Attempting to access another user’s data

Solution: Check subscription status and permissions

Email Not Verified

Error: "Email verification required"Solution: Check email for verification link or resend verification

Error Response Format

{
  "success": false,
  "error": "Authentication required",
  "code": "AUTH_REQUIRED"
}

Token Management

Token Expiration

JWT tokens have a limited lifespan:

Standard tokens: 24 hours
Remember me tokens: 30 days
Refresh threshold: Re-authenticate before expiration

Handling Expired Tokens

When you receive a 401 error:

Check if the token has expired
Re-authenticate to get a new token
Retry the original request
Implement automatic refresh in your application

Security Best Practices

Token Storage

Store tokens securely (encrypted)
Never expose tokens in URLs
Use secure, httpOnly cookies when possible
Clear tokens on logout

Network Security

Always use HTTPS
Validate SSL certificates
Implement request timeouts
Monitor for unusual access patterns

Rate Limiting

Authentication endpoints have specific rate limits:

Endpoint	Limit	Window
`/api/login`	5 attempts	15 minutes
`/api/register`	3 attempts	1 hour
`/api/verification/resend`	5 attempts	30 minutes

Exceeding rate limits will result in temporary IP blocking. Contact support if you need higher limits for legitimate use cases.

Testing Authentication

Test Your Integration

Verify your authentication setup:

# 1. Login and capture token
LOGIN_RESPONSE=$(curl -s -X POST https://app.medisync.me/api/login \
  -H "Content-Type: application/json" \
  -d '{"email": "your@email.com", "password": "your_password"}')

# 2. Extract token
TOKEN=$(echo $LOGIN_RESPONSE | jq -r '.token')

# 3. Test protected endpoint
curl -X GET "https://app.medisync.me/api/user/profile" \
  -H "Authorization: Bearer $TOKEN"

Next Steps

API Reference

Explore all available endpoints and their requirements

Getting Started

​Overview

​Authentication Flow

​Registration

​Create New Account

​Registration Requirements

​Login

​Obtain JWT Token

​Login Parameters

​Using JWT Tokens

​Authorization Header

​Example API Request

​Token Structure

​Authorization Levels

​User Identification

​Subscription Requirements

​Data Access Control

​Error Handling

​Authentication Errors

​Error Response Format

​Token Management

​Token Expiration

​Handling Expired Tokens

​Security Best Practices

Token Storage

Network Security

​Rate Limiting

​Testing Authentication

​Test Your Integration

​Next Steps

API Reference

Overview

Authentication Flow

Registration

Create New Account

Registration Requirements

Login

Obtain JWT Token

Login Parameters

Using JWT Tokens

Authorization Header

Example API Request

Token Structure

Authorization Levels

User Identification

Subscription Requirements

Data Access Control

Error Handling

Authentication Errors

Error Response Format

Token Management

Token Expiration

Handling Expired Tokens

Security Best Practices

Rate Limiting

Testing Authentication

Test Your Integration

Next Steps