Security & Authentication

The NPCA EMR Clinical Data Submission API uses OAuth 2.0 with Bearer Token authentication to secure all endpoints. This section provides comprehensive details on authentication flows, token management, and security requirements.

Security Overview

Parameter	Specification
Protocol	HTTPS (TLS 1.2 or higher)
Authentication	OAuth 2.0 Bearer Token
Grant Type	Password Grant & Refresh Token
Token Type	Bearer Token
Base URL	https://demo-authena.ddmit.site

Authentication Flow

1. Initial Authentication (Login)

To obtain an access token, make a POST request to the authentication endpoint with your credentials.

Endpoint: POST /oauth/token

Headers:

Accept: application/json
Content-Type: application/x-www-form-urlencoded

Request Body (URL-encoded):

username={your_username}
password={your_password}
client_id={your_client_id}
client_secret={your_client_secret}
grant_type=password

Example Request:

curl -X POST https://demo-authena.ddmit.site/oauth/token \
  -H "Accept: application/json" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=your_username" \
  -d "password=your_password" \
  -d "client_id=your_client_id" \
  -d "client_secret=your_client_secret" \
  -d "grant_type=password"

Response:

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...",
  "refresh_token": "def50200a1b2c3d4e5f6...",
  "token_type": "Bearer",
  "expires_in": 172800
}

2. Refresh Token

When your access token expires, use the refresh token to obtain a new access token without re-entering credentials.

Endpoint: POST /oauth/token

Headers:

Accept: application/json
Content-Type: application/x-www-form-urlencoded

Request Body (URL-encoded):

refresh_token={your_refresh_token}
client_id={your_client_id}
client_secret={your_client_secret}
grant_type=refresh_token

Example Request:

curl -X POST https://demo-authena.ddmit.site/oauth/token \
  -H "Accept: application/json" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "refresh_token=your_refresh_token" \
  -d "client_id=your_client_id" \
  -d "client_secret=your_client_secret" \
  -d "grant_type=refresh_token"

Response:

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...",
  "refresh_token": "def50200a1b2c3d4e5f6...",
  "token_type": "Bearer",
  "expires_in": 172800
}

API Request Authentication

Once you have an access token, include it in all API requests using the Bearer authentication scheme.

Required Headers for API Calls

Header	Value	Description
Authorization	Bearer {access_token}	OAuth 2.0 Bearer token
Content-Type	application/json	Request content type
Accept	application/json	Response content type
X-System-Code	{system_code}	System identifier provided by NPCA
X-Health-Facility-Code	{facility_code}	Health facility identifier provided by NPCA

Example Authenticated Request

curl -X POST https://demo-authena.ddmit.site/api/v1/external/visits \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9..." \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-System-Code: SHCH" \
  -H "X-Health-Facility-Code: 121020" \
  -d '{
    "visits": [...]
  }'

Security Best Practices

Token Management

• Store tokens securely: Never expose access tokens in client-side code or logs
• Implement token refresh: Automatically refresh tokens before expiration
• Handle token expiration: Implement proper error handling for 401 Unauthorized responses
• Use HTTPS only: All authentication requests must use HTTPS

Credential Security

• Protect client credentials: Store client_id and client_secret securely
• Use environment variables: Never hardcode credentials in source code
• Rotate credentials regularly: Follow your organization's credential rotation policy

Error Handling

Common authentication errors and their meanings:

Status Code	Error	Description
400	invalid_request	Missing or invalid request parameters
400	invalid_client	Invalid client credentials
400	invalid_grant	Invalid username/password or refresh token
401	unauthorized	Invalid or expired access token
403	forbidden	Valid token but insufficient permissions

Example Error Response

{
  "error": "invalid_grant",
  "error_description": "The provided authorization grant is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client."
}

Integration Checklist

• [ ] Obtain client credentials from NPCA
• [ ] Implement login flow with proper error handling
• [ ] Store tokens securely
• [ ] Implement automatic token refresh
• [ ] Include all required headers in API requests
• [ ] Test authentication with demo environment
• [ ] Implement proper error handling for authentication failures