Authentication API

The authentication system provides secure user registration, login, and session management with support for multiple user profiles.

Overview

Authentication Method: JWT (JSON Web Tokens)
Token Types: Access Token (24 hours) + Refresh Token (30 days)
Verification: SMS/WhatsApp OTP
Multi-Factor: 2FA support (optional)

Endpoints

User Registration

Standard Registration

Creates a new user account with password.

POST /auth/sign_up

Request Body:

{
  "user_signup_form": {
    "country_code": "91",
    "phone_number": "9876543210",
    "password": "SecurePass@123",
    "password_confirmation": "SecurePass@123",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "signed_up_as": "clinic",
    "timezone": "Asia/Kolkata",
    "invite_code": "INVITE123" // Optional
  }
}

Parameters:

Field	Type	Required	Description
country_code	string	Yes	Country calling code (91, 1, 44, etc.)
phone_number	string	Yes	10-15 digit phone number
password	string	Yes	Min 8 chars, must include uppercase, lowercase, number/symbol
password_confirmation	string	Yes	Must match password
first_name	string	Yes	User's first name
last_name	string	No	User's last name
email	string	No	Valid email address
signed_up_as	string	Yes	One of: patient, doctor, clinic, lab, pharmacy
timezone	string	No	User's timezone (default: Asia/Kolkata)
invite_code	string	No	Invitation code if applicable

Success Response:

{
  "success": true,
  "data": {
    "user": {
      "id": 123,
      "phone_number": "9876543210",
      "country_code": "91",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@example.com",
      "verified": false,
      "verification_required": true
    },
    "message": "Verification code sent to your phone"
  }
}

Error Response:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": {
      "phone_number": ["has already been taken"],
      "password": ["is too short (minimum is 8 characters)"]
    }
  }
}

OTP Registration

Creates a user account without password (OTP-only authentication).

POST /auth/otp_sign_up

Request Body:

{
  "user_signup_form": {
    "country_code": "91",
    "phone_number": "9876543210",
    "signed_up_as": "patient",
    "first_name": "Jane",
    "last_name": "Smith"
  }
}

Response: Same as standard registration

User Verification

Verify OTP Code

Verifies the OTP sent during registration or login.

POST /auth/verify_user

Request Body:

{
  "country_code": "91",
  "phone_number": "9876543210",
  "verification_code": "12345"
}

Success Response:

{
  "success": true,
  "data": {
    "user": {
      "id": 123,
      "first_name": "John",
      "last_name": "Doe",
      "verified": true,
      "user_accounts": [
        {
          "user_account_id": 456,
          "account_type": "clinic",
          "role": "owner",
          "profile": {
            "clinic_id": 789,
            "clinic_name": "City Health Clinic",
            "logo_url": "https://..."
          }
        }
      ]
    },
    "auth_token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
    "refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
    "token_expires_at": "2024-01-16T10:30:00Z"
  }
}

Resend Verification Code

Resends OTP to the user's phone number.

POST /auth/resend_verification_code

Request Body:

{
  "country_code": "91",
  "phone_number": "9876543210"
}

Authenticates user with phone number and password.

POST /auth/sign_in

Request Body:

{
  "user_signin_form": {
    "country_code": "91",
    "phone_number": "9876543210",
    "password": "SecurePass@123",
    "platform": "web" // Optional: web, ios, android
  }
}

Success Response:

{
  "success": true,
  "data": {
    "user": {
      "id": 123,
      "first_name": "John",
      "verified": true,
      "user_accounts": [
        {
          "user_account_id": 456,
          "account_type": "doctor",
          "role": "owner",
          "profile": {
            "doctor_id": 101,
            "name": "Dr. John Doe",
            "speciality": "Cardiologist"
          }
        },
        {
          "user_account_id": 457,
          "account_type": "clinic",
          "role": "consultant",
          "profile": {
            "clinic_id": 202,
            "clinic_name": "Heart Care Center"
          }
        }
      ]
    },
    "auth_token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
    "refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
    "token_expires_at": "2024-01-16T10:30:00Z"
  }
}

Initiates OTP-based login.

POST /auth/otp_sign_in

Request Body:

{
  "country_code": "91",
  "phone_number": "9876543210"
}

Response: Returns success with message to verify OTP

Token Management

Refresh Access Token

Gets a new access token using refresh token.

POST /auth/refresh

Request Body:

{
  "refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
  "user_id": 123
}

Success Response:

{
  "success": true,
  "data": {
    "auth_token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
    "token_expires_at": "2024-01-16T10:30:00Z"
  }
}

Logout

Invalidates the current session.

POST /auth/logout

Headers:

Authorization: Bearer YOUR_TOKEN

Success Response:

{
  "success": true,
  "message": "Logged out successfully"
}

Password Management

Reset Password Request

Initiates password reset flow.

POST /auth/reset_password

Request Body:

{
  "country_code": "91",
  "phone_number": "9876543210"
}

Verify Reset Code

Verifies the reset password OTP.

POST /auth/verify_reset_password_code

Request Body:

{
  "country_code": "91",
  "phone_number": "9876543210",
  "reset_password_token": "12345"
}

Change Password

Updates user password after verification.

POST /auth/change_password

Request Body:

{
  "country_code": "91",
  "phone_number": "9876543210",
  "reset_password_token": "12345",
  "new_password": "NewSecurePass@456",
  "password_confirmation": "NewSecurePass@456"
}

Links social media account to user profile.

POST /auth/social_connect

Request Body:

{
  "auth_service": {
    "auth_type": "facebook",
    "uid": "facebook_user_id_123",
    "credentials": {
      "token": "facebook_access_token",
      "refresh_token": "facebook_refresh_token",
      "expires_at": 1642248000
    },
    "user_info": {
      "email": "user@facebook.com",
      "name": "John Doe",
      "image": "https://..."
    }
  }
}

Supported Providers:

facebook
google
linkedin
twitter

Gets all linked social accounts.

GET /auth/social_connect

Headers:

Authorization: Bearer YOUR_TOKEN

Profile Management

Switch Active Profile

Changes the active user profile/account.

POST /auth/switch_profile

Request Body:

{
  "user_account_id": 456
}

Success Response:

{
  "success": true,
  "data": {
    "active_profile": {
      "user_account_id": 456,
      "account_type": "clinic",
      "role": "owner",
      "profile": {
        "clinic_id": 789,
        "clinic_name": "City Health Clinic"
      }
    },
    "permissions": [
      "manage_clinic",
      "view_patients",
      "manage_practice_finance"
    ]
  }
}

Token Structure

Access Token Claims

{
  "user_id": 123,
  "exp": 1642334400,
  "iat": 1642248000,
  "jti": "unique_token_id"
}

Using Tokens

Include the token in the Authorization header:

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...

Error Codes

Code	Description	Resolution
AUTH001	Invalid credentials	Check phone number and password
AUTH002	Token expired	Use refresh token to get new access token
AUTH003	Invalid token	Re-authenticate
AUTH004	Account not verified	Complete OTP verification
AUTH005	Account suspended	Contact support
AUTH006	Invalid OTP	Request new OTP
AUTH007	OTP expired	Request new OTP
AUTH008	Too many attempts	Wait before trying again

Rate Limiting

Registration: 5 requests per hour per IP
Login: 10 requests per hour per phone number
OTP Request: 5 requests per hour per phone number
Password Reset: 3 requests per hour per phone number

Security Best Practices

Password Requirements:
- Minimum 8 characters
- At least one uppercase letter
- At least one lowercase letter
- At least one number or special character
Token Storage:
- Store tokens securely (Keychain on iOS, Keystore on Android)
- Never store tokens in plain text
- Clear tokens on logout
OTP Handling:
- OTPs expire after 10 minutes
- Maximum 5 verification attempts
- New OTP invalidates previous ones
HTTPS Only:
- All API calls must use HTTPS
- HTTP requests will be rejected

Testing

Test Credentials

For staging environment only:

{
  "test_user": {
    "country_code": "91",
    "phone_number": "9999999999",
    "password": "Test@1234",
    "otp": "12345"
  }
}

Authentication API

Overview

Endpoints

User Registration

Standard Registration

OTP Registration

User Verification

Verify OTP Code

Resend Verification Code

Token Management

Refresh Access Token

Logout

Password Management

Reset Password Request

Verify Reset Code

Change Password

Profile Management

Switch Active Profile

Token Structure

Access Token Claims

Using Tokens

Error Codes

Rate Limiting

Security Best Practices

Testing

Test Credentials

Postman Examples

Migration Guide

From v1.0 to v1.1

Next Steps

On this page

Authentication API

OverviewCopy Anchor Link

EndpointsCopy Anchor Link

User RegistrationCopy Anchor Link

Standard RegistrationCopy Anchor Link

OTP RegistrationCopy Anchor Link

User VerificationCopy Anchor Link

Verify OTP CodeCopy Anchor Link

Resend Verification CodeCopy Anchor Link

User LoginCopy Anchor Link

Sign In with PasswordCopy Anchor Link

Sign In with OTPCopy Anchor Link

Token ManagementCopy Anchor Link

Refresh Access TokenCopy Anchor Link

LogoutCopy Anchor Link

Password ManagementCopy Anchor Link

Reset Password RequestCopy Anchor Link

Verify Reset CodeCopy Anchor Link

Change PasswordCopy Anchor Link

Social AuthenticationCopy Anchor Link

Connect Social AccountCopy Anchor Link

List Social ConnectionsCopy Anchor Link

Profile ManagementCopy Anchor Link

Switch Active ProfileCopy Anchor Link

Token StructureCopy Anchor Link

Access Token ClaimsCopy Anchor Link

Using TokensCopy Anchor Link

Error CodesCopy Anchor Link

Rate LimitingCopy Anchor Link

Security Best PracticesCopy Anchor Link

TestingCopy Anchor Link

Test CredentialsCopy Anchor Link

Postman ExamplesCopy Anchor Link

Migration GuideCopy Anchor Link

From v1.0 to v1.1Copy Anchor Link

Next StepsCopy Anchor Link

On this page

Overview

Endpoints

User Registration

Standard Registration

OTP Registration

User Verification

Verify OTP Code

Resend Verification Code

User Login

Sign In with Password

Sign In with OTP

Token Management

Refresh Access Token

Logout

Password Management

Reset Password Request

Verify Reset Code

Change Password

Social Authentication

Connect Social Account

List Social Connections

Profile Management

Switch Active Profile

Token Structure

Access Token Claims

Using Tokens

Error Codes

Rate Limiting

Security Best Practices

Testing

Test Credentials

Postman Examples

Migration Guide

From v1.0 to v1.1

Next Steps