Skip to main content

Authorization

To have your application be able to interact with certified FHIR APIs you must first obtain authorization (Bearer token). To accomplish this, you must reach these endpoints:

  • Authorize Endpoint
  • Token Endpoint

Authorize Endpoint​

To authorize your application you must use the authorize endpoint to grant your app access to data from Netsmart APIs. You must have your authorized Redirect URI included with your application registration to use this endpoint:

  • GET [base]/authorize

Authorization Code Flow​

The authorization code flow is for all user authentication scenarios. Public Clients must use the authorization code flow with Proof Key for Code Exchange (PKCE) to authenticate, as a secret cannot be kept secure.

Authorization Request Example​

Authorization Request
curl -X GET https://oauth.netsmartcloud.com/authorize? \
    'response_type=code&' \
    'client_id={client id}&' \
    'redirect_uri={registered redirect uri}&' \
    'scope=launch%2Fpatient+openid+fhirUser+offline_access+patient%2FPatient.read&' \
    'state=627bf2ef-8211-4677-aee0-1c3a1e1edc31&' \
    'aud=https%3A%2F%2Ffhir.netsmartcloud.com%2Fuscore%2Fv1&'

Parameters​

NameData TypeDescription
response_typeStringThis is set to “code”.
client_idStringThis is the client id assigned to your application at registration.
redirect_uriStringThis is the URL we are to redirect the user following login to provide your app the authorization code. This must be authorized in your application’s registration.
scopeStringThis is a space-delimited list of scope that are being requested by your application. At minimum the openid scope must be requested.

Include the appropriate SMART App Launch and Clinical scopes to access the FHIR endpoints. (E.g., launch and patient/Patient.read)
stateStringThis value is a random, one time use string provided by your application that will be returned unmodified in our response. This is used to help prevent cross-site forgery attacks.
audStringThis is the base URL of the FHIR endpoint you intend to utilize.
code_challengeStringThis is required when using the authorization code flow with PKCE. This is a single use string used to validate the subsequent token request.
code_challenge_methodStringThis is required when using the authorization code flow with PKCE. This value indicates the encryption method used to create your code challenge. I.e., S256 for SHA256 encryption.

Response Example​

Response
curl -X GET {redirect uri}? \
    'code={authorization code}&' \
    'state={state value from request}'

Parameters​

NameData TypeDescription
codeStringThis is an obscure code that your application will use to exchange for a token at the token endpoint.
stateStringThis value is the same value provided in the request.

Token Endpoint​

The token endpoint is used by your application to obtain tokens of use case and authentication flow. This endpoint is accessed by your application rather than by the user directly.

Authentication​

Requests to this endpoint must be authenticated. Below are available options for authenticating with the token endpoint.

Using a Client Secret​

To authenticate using a client secret, include the client_id and client_secret parameters in your x-form-urlencoded payload with your other parameters.

Using a Client Secret
curl -X POST https://oauth.netsmartcloud.com/token \
    -H 'Content-Type: x-form-urlencoded' \
    -d 'client_id={client_id}' \
    -d 'client_secret={client_secret}' 
    // additional request parameters

Alternatively, you may also use the Basic Auth to pass the client id and secret base64 encoded in the Authorization header.

Using Base64 Client Secret
curl -X POST https://oauth.netsmartcloud.com/token \
    -H 'Authorization: Basic xxxxxxxxx (base64 encoding of {client_id}:{client_secret})'

Using a JWK Set​

You may also provide a client assertion as a signed JWT. You must have your JWK Set URI included with your application registration to use this.

Using a JWK Set
curl -X POST https://oauth.netsmartcloud.com/token \
    -H 'Content-Type: x-form-urlencoded' \
    -d 'client_assertion={signed JWT}' \
    -d 'client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer' 
    // additional request parameters

Request​

In the previous section we saw that the Authorize endpoint returned the user of your application with a code. Your application will then submit the code to the token endpoint in exchange for a token.

Request Token
curl -X POST https://oauth.netsmartcloud.com/token \
    -H 'Content-Type: x-form-urlencoded' \
    // additional request parameters

Parameters​

NameData TypeDescription
grant_typeStringThis may be:
• authorization_code (when exchanging a code for a token)
• refresh_token (when requesting a new access token)
• client_credential (when requesting a token for your client with our user interaction)
redirect_uriStringRequired for the authorization_code grant type. Must match the redirect uri registered for your application and the request to the authorize endpoint.
codeStringRequired for the authorization_code grant type. This is the code returned from the authorize endpoint.
code_verifierStringRequired for the authorization_code grant type when using PKCE.
refresh_tokenStringRequired for the refresh_token grant type. This is the refresh token returned by the authorize endpoint.
scopeStringRequired for the client_credentials and refresh_token grant type.
sdk_scopeStringThis is only required when the client application is authorized to access multiple SDK scopes to indicate which to obtain a token for. We recommend registering separate applications for each SDK scope you need to access.

Response​

The response received will vary based on the authentication flow and what was authorized. Every response will include at least the following output parameters:

  • access_token
  • token_type (Always "Bearer")
  • expires_in
  • scope

Response Example​

{
 "access_token": "xxxxxxxxxx",
 "token_type": "Bearer",
 "id_token": "yyyyyyyyy",
 "expires_in": 3600,
 "refresh_token": "zzzzzzzzzzz",
 "scope": "launch/patient openid fhirUser offline_access patient/Patient.read ",
 "patient": "123",
 "need_patient_banner": true,
 "smart_style_url": "https://oauthtest.netsmartcloud.com/styles/smart_v1.json"
}

SMART on FHIR​

SMART on FHIR defines patterns/standards for healthcare exchange using FHIR and OAuth/OpenID.

There are three basic access scenarios:

  • Patient Access (Authorization Code Flow)
  • Practitioner Access (Authorization Code Flow) and
  • Backend Access (Client Credentials Grant Type)

Patient Access​

Patient Access allows for FHIR clients to authenticate by using the authorization_code grant type.

We support authenticating your application using a Private Key JWT. To use this method you will need to include your JWK Set URI with the registration of your application.

Authorization Code Flow with Private Key JWT
curl -X POST https://oauth.netsmartcloud.com/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d grant_type=authorization_code \
  -d code=123456789 \
  -d redirect_uri=YOUR_REDIRECT_URI \
  -d client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer \
  -d client_assertion=YOUR_SIGNED_JWT \
  -d code_verifier=4534576
Authorization Code Flow with Client Secret
curl -X POST https://oauth.netsmartcloud.com/token \
  -H "Authorization: Basic xxxxxxxxx (base64 encoding of {client_id}:{client_secret})" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d grant_type=authorization_code \
  -d code=123456789 \
  -d redirect_uri=YOUR_REDIRECT_URI \
  -d code_verifier=4534576

Practitioner Access​

Practitioner Access allows for FHIR clients to authenticate by using the authorization_code grant type.

We support authenticating your application using a Private Key JWT. To use this method you will need to include your JWK Set URI with the registration of your application.

Authorization Code Flow with Private Key JWT
curl -X POST https://oauth.netsmartcloud.com/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d grant_type=authorization_code \
  -d code=123456789 \
  -d redirect_uri=YOUR_REDIRECT_URI \
  -d client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer \
  -d client_assertion=YOUR_SIGNED_JWT \
  -d code_verifier=4534576

This most commonly used method is to pass the client id and secret as parameters in the requests.

Authorization Code Flow with Client Secret
curl -X POST https://oauth.netsmartcloud.com/token \
  -H "Authorization: Basic xxxxxxxxx (base64 encoding of {client_id}:{client_secret})" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d grant_type=authorization_code \
  -d code=123456789 \
  -d redirect_uri=YOUR_REDIRECT_URI \
  -d code_verifier=4534576

Backend Access​

Backend Access allows for FHIR clients to authenticate without a user using the client_credentials grant type.

We support authenticating your application using a Private Key JWT. To use this method you will need to include your JWK Set URI with the registration of your application.

Client Credentials Flow with Private Key JWT
curl -X POST https://oauth.netsmartcloud.com/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d grant_type=client_credentials \
  -d client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer \
  -d client_assertion=YOUR_SIGNED_JWT \
  -d scope=system/Patient.read%20system/AllergyIntolerance.read

This most commonly used method is to pass the client id and secret as parameters in the requests.

Client Credentials Flow with Client Secret
curl -X POST https://oauth.netsmartcloud.com/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d grant_type=client_credentials \
  -d client_id=YOUR_CLIENT_ID \
  -d client_secret=YOUR_CLIENT_SECRET \
  -d scope=system/Patient.read%20system/AllergyIntolerance.read