Summary
ClinSpark has APIs which can be used by customers. Currently these are scoped for two use cases:
Integration with a customer recruitment website
Programmatic execution and retrieval of reports.
IQVIA can offer suggestions for how to use these APIs, however we cannot support or assist with implementation and ongoing support of customer-specific mechanisms that rely on them.
Learning API Functions
Each of the API documentation pages contain information covering the scope and purpose of each interface. Additionally, there is an embedded Swagger UI client on the page with the purpose of allowing customers a simple interactive way to try out certain functions and learn how the API can be used. This video provides a quick demonstration on how to use the embedded functions.
https://vimeo.com/821961555/b7e6fb5359?share=copyWe expect customers to first learn about API invocations with the Swagger UI client on this documentation site. Once you have successfully invoked the API with this client, you will find that it provides client bindings and command line invocation patterns that will work directly for integrations or other API clients/tooling.
For support requests, we ask similarly that customers first explore and troubleshoot using the Swagger client and include results of testing when reaching out via service desk.
Prerequisites for use
In order to use the interactive Swagger UI, you need the following:
A ClinSpark user account on the instance/environment used (‘server’)
The user account must have the
apiRole Action in one of their assigned RolesIn ClinSpark version 23.3 and greater, the user account must be setup with at least one of the supported authentication schemes (see below)
Supported Authentication Schemes
ClinSpark supports Basic HTTP (basic auth) and Bearer HTTP (token) authentication schemes.
As customers upgrade to more recent versions of ClinSpark, they are encouraged to explore using API tokens and adopt use for API accounts accordingly. Support for Basic Authentication may be deprecated in a future release of ClinSpark, to be replaced with authentication schemes that meet stronger security standards and modern best practices.
Basic HTTP
All versions of ClinSpark support Basic HTTP Authentication via username and password. Starting in version 23.3, use of basic auth is supported with a specific account setting.
Within the Administration > Users component, edit an account intended for API use.
Within the Update User modal, select the setting to enable basic auth:
Bearer HTTP Tokens
ClinSpark versions 23.3 and greater support Bearer HTTP Authentication.
API tokens are generated and managed with ClinSpark user accounts for this purpose. These features are accessed in the Administration > Users component.
Multiple API tokens can be setup per account.
Supporting use of these features are specific Role Actions that allow users to view and manage tokens on accounts.
User Account Permissions
A specific API role action must be assigned to a user account in ClinSpark to use the API. For most use cases, these are typically accounts that facilitate workflows via ClinSpark web services. Integration applications that use specific ‘system’ accounts in ClinSpark must also be configured with this role action.
An example of how these API permissions apply to Recruitment website integrations can be reviewed in this article: https://foundryhealth.atlassian.net/wiki/spaces/DOCS/pages/3700817953/Recruitment+Website+Integration#Granting-the-Website-Integrators-Appropriate-Access
Other than the assigned role action and intended use, there are no unique properties of accounts used for API invocation.
Customers are expected to manage all user account credentials intended for API use. We strongly suggest customers follow security best practices by assigning highly complex passwords (up to 255 characters) to the accounts and rotating them regularly. More information about ClinSpark user account management can be viewed in this article: User Management
We discourage the practice of customers creating, sharing, and soliciting use of integration user accounts that contain API role actions outside of site organization teams.
Customers are encouraged to create and manage multiple API users if they decide to adhere to a stricter credential management practice. This is our recommendation, so customers can properly process leavers/joiners with their own service account credentials, instead of having a pool of team members using shared credentials for singular service accounts.