Authorization
For a client application to access REST API resources, it must be authorized as a safe visitor. To implement this authorization, use a connected app and an OAuth 2.0 authorization flow.
A connected app requests access to REST API resources on behalf of the client application. For a connected app to request access, it must be integrated with your org’s REST API using the OAuth 2.0 protocol. OAuth 2.0 is an open protocol that authorizes secure data sharing between applications through the exchange of tokens.
For instructions to configure a connected app, see Create a Connected App in Salesforce Help. Specifically, follow the instructions in Enable OAuth Settings for API Integration.
A connected app can use the OAuth authorization protocol to access protected resources. As part of the protocol, OAuth default scopes fine-tune the app’s permissions to access protected resources in Salesforce. However, these default scopes are insufficient when an external entity hosts the protected resource. In this scenario, Salesforce plays the role of OAuth authentication and authorization provider, but it has little knowledge about the resource it’s protecting. To define a connected app’s permissions to access protected resources hosted by an external entity, create an OAuth custom scope. The custom scope tells the external entity which information the connected app is authorized to access.
The following custom scopes are available for the Healthcare APIs:
| Resource | Method | Custom Scopes | Description |
|---|---|---|---|
| Medication | GET | user_medication_read OR user_all_read OR system_all_read | Allows read access to the Medication resource. |
| POST, PUT | user_medication_write OR user_all_write OR system_all_write OR system_medication_write | Allows write access to the Medication resource. | |
| Condition | GET | user_condition_read OR user_all_read OR system_all_read | Allows read access to the Condition resource. |
| POST, PUT | user_condition_write OR user_all_write OR system_all_write OR system_condition_write | Allows write access to the Condition resource. | |
| AllergyIntolerance | GET | user_allergyIntolerance_read OR user_all_read OR system_all_read | Allows read access to the AllergyIntolerance resource. |
| POST, PUT | user_allergyIntolerance_write OR user_all_write OR system_all_write OR system_allergyIntolerance_write | Allows write access to the AllergyIntolerance resource. | |
| Procedure | GET | user_procedure_read OR user_all_read OR system_all_read | Allows read access to the Procedure resource. |
| POST, PUT | user_procedure_write OR user_all_write OR system_all_write OR system_procedure_write | Allows write access to the Procedure resource. | |
| Claim | GET | system_claim_read OR system_all_read | Allows read access to the Claim resource. |
| POST, PUT | system_claim_write OR system_all_write | Allows write access to the Claim resource. | |
| Patient | GET | user_patient_read OR user_all_read OR system_patient_read OR system_all_read | Allows read access to the Patient resource. |
| POST, PUT | user_patient_write OR user_all_write OR system_patient_write OR system_all_write | Allows write access to the Patient resource. | |
| Practitioner | GET | user_practitioner_read OR user_all_read OR system_practitioner_read OR system_all_read | Allows read access to the Practitioner resource. |
| POST, PUT | user_practitioner_write OR user_all_write OR system_practitioner_write OR system_all_write | Allows write access to the Practitioner resource. | |
| Practitioner Role | GET | user_practitionerRole_read OR user_all_read OR system_practitionerRole_read OR system_all_read | Allows read access to the Practitioner Role resource. |
| POST, PUT | user_practitionerRole_write OR user_all_write OR system_practitionerRole_write OR system_all_write | Allows write access to the Practitioner Role resource. | |
| Organization | GET | user_organization_read OR user_all_read OR system_organization_read OR system_all_read | Allows read access to the Organization resource. |
| POST, PUT | user_organization_write OR user_all_read OR system_organization_write OR system_all_write | Allows write access to the Organization resource. | |
| Encounter | GET | user_encounter_read OR user_all_read OR system_encounter_read OR system_all_read | Allows read access to the Encounter resource. |
| POST, PUT | user_encounter_write OR user_all_read OR system_encounter_write OR system_all_write | Allows write access to the Encounter resource. | |
| Location | GET | user_location_read OR user_all_read OR system_location_read OR system_all_read | Allows read access to the Location resource. |
| POST, PUT | user_location_write OR user_all_read OR system_location_write OR system_all_write | Allows write access to the Location resource. | |
| Observation | GET | user_observation_read OR user_all_read OR system_observation_read OR system_all_read | Allows read access to the Observation resource. |
| POST, PUT | user_observation_write OR user_all_write OR system_observation_write OR system_all_write | Allows write access to the Observation resource. | |
| DiagnosticReport | GET | user_diagnosticReport_read OR user_all_read OR system_diagnosticReport_read OR system_all_read | Allows read access to the DiagnosticReport resource. |
| POST, PUT | user_diagnosticReport_write OR user_all_write OR system_diagnosticReport_write OR system_all_write | Allows write access to the DiagnosticReport resource. | |
| ServiceRequest | GET | user_serviceRequest_read OR user_all_read OR system_serviceRequest_read OR system_all_read | Allows read access to the ServiceRequest resource. |
| POST, PUT | user_serviceRequest_write OR user_all_write OR system_serviceRequest_write OR system_all_write | Allows write access to the ServiceRequest resource. | |
| Medication Request | GET | user_medicationRequest_read OR user_all_read OR system_medicationRequest_read OR system_all_read | Allows read access to the Medication Request resource. |
| POST, PUT | user_medicationRequest_write OR user_all_write OR system_medicationRequest_write OR system_all_write | Allows write access to the Medication Request resource. | |
| Immunization | GET | user_immunization_read OR user_all_read OR system_immunization_read OR system_all_read | Allows read access to the Immunization resource. |
| POST, PUT | user_immunization_write OR user_all_write OR system_immunization_write OR system_all_write | Allows write access to the Immunization resource. | |
| Medication Statement | GET | user_medicationStatement_read OR user_all_read OR system_medicationStatement_read OR system_all_read | Allows read access to the Medication Statement resource. |
| POST, PUT | user_medicationStatement_write OR user_all_write OR system_medicationStatement_write OR system_all_write | Allows write access to the Medication Statement resource. | |
| CarePlan | GET | user_carePlan_read OR user_all_read OR system_carePlan_read OR system_all_read | Allows read access to the CarePlan resource. |
| POST, PUT | user_carePlan_write OR user_all_write OR system_all_write OR system_carePlan_write | Allows write access to the CarePlan resource. | |
| Goal | GET | user_goal_read OR user_all_read OR system_goal_read OR system_all_read | Allows read access to the Goal resource. |
| POST, PUT | user_goal_write OR user_all_write OR system_all_write OR system_goal_write | Allows write access to the Goal resource. | |
| RelatedPerson | GET | user_relatedPerson_read OR user_all_read OR system_relatedPerson_read OR system_all_read | Allows read access to the RelatedPerson resource. |
| POST, PUT | user_relatedPerson_write OR user_all_write OR system_all_write OR system_relatedPerson_write | Allows write access to the RelatedPerson resource. | |
| Bundle | POST | system_bundle_read OR system_bundle_write | Allows write access to the Bundle resource. |
For instructions on how to create custom scopes in the Salesforce org, see OAuth Tokens and Scopes and Create a OAuth Custom Scope in Salesforce Help.
After you create an OAuth custom scope in your Salesforce org, you can assign it to a connected app to set data-access permissions for the app.
Note - You must assign the refresh_token scope to the connected app.
For detailed instructions, see Assign an OAuth Custom Scope to a Connected App in Salesforce Help.
OAuth authorization flows grant a client app restricted access to REST API resources on a resource server. Each OAuth flow offers a different process for approving access to a client app, but in general the flows consist of three main steps.
- To initiate an authorization flow, a connected app on behalf of a client app requests access to a REST API resource.
- In response, an authorizing server grants access tokens to the connected app.
- A resource server validates these access tokens and approves access to the protected REST API resource.
After reviewing and selecting an OAuth authorization flow, apply it to your connected app. For details about each supported flow, see OAuth Authorization Flows in Salesforce Help.