Getting Started

Generate your own RSA or EC key pair — for example, from a terminal with openssl installed (macOS, Linux, WSL, or Git Bash on Windows):

openssl req -x509 -newkey rsa:2048 -nodes -keyout key.pem -out cert.pem -days 365

On Windows without Git Bash, use PowerShell with the command below:

& "C:\Program Files\Git\usr\bin\openssl.exe" req -x509 -newkey rsa:2048 -nodes -keyout key.pem -out cert.pem -days 365

Submit a provider organization registration request with your NPI and the public certificate (cert.pem) — never submit key.pem; keep it on your own systems. Once approved, we create a client app registration, register your public certificate as its authentication key, and email you a client_id.

Register a Provider Organization

The Provider Access API requires certificate-based authentication (private_key_jwt). Instead of sending a secret, your system signs a short-lived JWT with the private key matching the certificate you registered, and presents that signed JWT as the client_assertion. You typically don't need to hand-construct the JWT yourself — most OAuth/identity libraries build and sign the client_assertion for you, including Microsoft's MSAL (.NET, Java, Python, Node) and any generic OAuth client that supports private_key_jwt. Just point the library at your certificate and private key. See Microsoft's certificate credentials documentation for details on how the JWT assertion is signed and validated.

Request against the Microsoft identity platform token endpoint for our tenant (shown below). This is a fixed endpoint, so there is no discovery document to fetch first.

POST https://login.microsoftonline.com/1b61d231-46d1-4083-b5c4-5920b1c6202f/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=YOUR_CLIENT_ID
&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
&client_assertion=YOUR_SIGNED_JWT
&scope=api%3A%2F%2F%7Bprovider-api-client-id%7D%2F.default

A successful response returns:

{
  "access_token": "eyJ...",
  "token_type":   "Bearer",
  "expires_in":   3600
}

There is no refresh token in the client credentials grant — request a new token with the same call once the current one expires.

Include the access token in the Authorization header on every request to the Provider Access API base URL. All responses are returned as application/fhir+json.

GET https://cms-api.wasatch.org/provider/fhir/r4/Condition?patient=PATIENT_ID
Authorization: Bearer ACCESS_TOKEN
Accept: application/fhir+json

Your token's roles claim carries the app role assigned at approval — typically system.all.read, which grants read access to every supported resource type. See the Roles Reference for the full convention.

Error responses are returned as FHIR OperationOutcome resources:

{
  "resourceType": "OperationOutcome",
  "issue": [{
    "severity": "error",
    "code":     "forbidden",
    "diagnostics": "Provider is not attributed to patient 123456."
  }]
}

A valid system.all.read token does not grant access to every patient — each request is checked against the provider's recorded patient attributions. Requests for a patient who is not attributed to your organization's NPI are rejected with a 403 OperationOutcome even though the token itself is valid.