ESMD FHIR Implementation Guide
1.0.0 - esmd

ESMD FHIR Implementation Guide - Local Development build (v1.0.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

Esmd Authentication API

Introduction

The esMD Authentication API facilitates secure access to the esMD system by validating user credentials and providing access tokens for subsequent API requests. This guide provides comprehensive details to help developers integrate with the API effectively.

OAuth2 Authentication for esMD FHIR Services

The esMD system employs OAuth2 for securing API access. This section details the OAuth2 implementation to facilitate secure interactions with the esMD FHIR services.

OAuth2 Flow Overview

  1. Client Credentials: Obtain client credentials (client_id, client_secret and scope) from the esMD Operations team.
  2. Token Request: Send a POST request to the Auth API endpoint with the client credentials to receive an access token.
  3. Access Token: Use the access token received to authenticate subsequent API requests.

API URL Details

  • Operation Name: api/esmdf/ext/Auth/generate
  • Method: POST
  • Authentication Required: Yes

Endpoint URLs

  • UAT: https://val.cpiapigateway.cms.gov/api/esmdf/ext/auth/generate
  • PROD: https://cpiapigateway.cms.gov/api/esmdf/ext/auth/generate

Note: Tokens typically have a limited lifespan (e.g., 1800 seconds), after which they need to be refreshed.

Request Headers

Table 1: Auth API – Request Headers

Header Description Required Data Type Comments
clientid Contact the esMD Operations team to get the Client ID Yes String Example: 3fis5elmln49c3fklkfs5v20ml
client secret Contact the esMD Operations team to get the Client secret Yes String Example: 1ad4odlhll6jur6qfbaoa71o52...
Scope Scope to be entered based on API’s call. Yes String Example: hih/esmdfhir

Auth API Response

The system will validate the metadata elements sent in the request and respond accordingly.

Table 2: Auth API Response Codes

Type Code Status Resolution
Success 200 OK Request processed successfully. No action needed.
Error 400 Bad Request Missing or invalid headers or parameters. Check request headers or parameters and resubmit.
Error 401 Unauthorized Invalid client ID or client secret. Correct the details and resubmit.
Error 403 Forbidden Insufficient permissions or server config issues. Contact esMD Support.
Error 404 Not Found Invalid URL. Correct the endpoint URL and resubmit.
Error 500 Internal Server Error Unexpected server error. Contact esMD Support.
Error 502 Bad Gateway Contact esMD Support.
Error 503 Service Unavailable Contact esMD Support.

Note: In the case of failure (401, 403, 404, 500, 502, and 503), contact the esMD Service Desk at esMD_Support@cms.hhs.gov.

Example Responses

Success Response:

{
    "access_token": "eyJraWQiOiJQbUJ...",
    "expires_in": 1800,
    "token_type": "Bearer"
}

Failure Response:

{
    "error": "IDP ERROR: invalid_client"
}