Salvus Health provides a secure and modern RESTful API to enable seamless integration with third-party systems. The API supports robust interactions between our patient engagement platform and your pharmacy information system, ensuring data consistency and real-time synchronization where needed.
All API requests require secure authentication. Clients must first request an access token from Salvus Health’s authorization server. This token grants time-limited access to make HTTPS requests to Salvus Health services, using OAuth 2.0 industry-standard authentication protocols.
The API integration should allow for the creation and synchronization of patient profiles between Salvus Health and third-party applications. This will ensure a unified view of the patient across both platforms and supports smooth workflows, such as bookings, care flows, and follow-ups.
The Salvus Health API is versioned to ensure backward compatibility and stable integrations over time. Partners will be notified of any breaking changes well in advance.
Our development team provides support during the integration process, including sandbox access and technical guidance when needed.
All data exchanges between Salvus Health and third-party applications's platform will comply with GDPR data protection requirements. A separate Data Sharing or Processing Agreement will govern roles, responsibilities, and security protocols.
No patient data will be shared without lawful basis and appropriate patient consent where required and the sharing of patient data shall be limited to what is necessary for the purposes of the integration between the patient engagement system and the pharmacy information system. Each party will be responsible for implementing and maintaining appropriate security measures to protect patient information.
You need access token to be able to make authorized requests. We use OAuth 2.0 standard protocol.
Each access token is bound to a specific organization (pharmacy).
You can request the access token from Salvus-Health after reaching an agreement. The token will be shared via a secure channel and will have a long expiration period based on specific agreement.
If you believe the token has been compromised, Salvus can revoke it at any time upon request.
Once you've received your access token make sure you add the string "Bearer" to your authentication headers as shown below.
--header 'Authorization: Bearer 2FB3CEC7B1D62D8045169544A9DC2313613B525F06F2C96E29302FB-1'
Each access token is tied to a specific organization (pharmacy), so you must use the correct token for each one.
The Client Credentials flow is used for server-to-server authentication where no user interaction is required. Third-party applications can obtain an access token using their client credentials.
The following scopes may be requested based on your client authorization:
Every token is bound only to one organization. Hence, when requesting the token, the Organization.Identifier.{APB-NUMBER}
must be included in the scope request. For pharmacies in Belgium the scope that needs to be requested is based on the APB number, for example:
Organization.Identifier.{APB-NUMBER}
Note
Only one organization SCOPE can be requested per token. Asking multiple organizations will not work.
The
Salvus.Patient.Data.Standard.Read
- Can read non-medical patient data within the pharmacy scope
Salvus.Patient.Data.Standard.Edit
- Can edit non-medical patient data within the pharmacy scope
Salvus.Patient.Data.Standard.Write
- Can write non-medical patient data within the pharmacy scope
Salvus.Appointment.Read
- Can read appointments of the pharmacy
Salvus.Appointment.Edit
- Can edit appointments of the pharmacy
Salvus.Appointment.Write
- Can create appointments in the pharmacy
Note
You can only request scopes that your client ID is authorized for. Requesting unauthorized scopes will result in an invalid_scope error response.
POST /connect/token
Content-Type: application/x-www-form-urlencoded
client_id=salvus_integration
grant_type=client_credentials
client_secret=xxxxx
scope=Salvus.Api.Integration Organization.Identifier.APB000111 Salvus.Appointment.Read
POST /connect/token HTTP/1.1
Host: https://api.sandbox.salvus-health.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 284
client_id={your_clientid}&grant_type=client_credentials&client_secret={your_client_secret}&scope=Salvus.Api.Integration%20Organization.Identifier.APB000111%20Salvus.Appointment.Read
{
"access_token": "2FB3CEC7B1D62D804516...",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "Salvus.Api.Integration Organization.Identifier.APB000111 Salvus.Appointment.Read"
}
{
"error": "invalid_client",
"error_description": "Invalid client credentials"
}
Include the token in API requests:
Authorization: Bearer {access_token}
invalid_client
- Invalid client credentialsinvalid_grant
- Invalid grant typeinvalid_scope
- Requested scope is invalidunauthorized_client
- Client not authorized for this grant type
Important
1 - Store client credentials securely
2 - Handle token expiration gracefully
3 - Use HTTPS for all requests
4 - Request minimal required scopes
5 - Revoke tokens immediately if there is any risk of compromise or leak
It's important to revoke tokens when:
HTTP Method
POST /connect/revocation
Headers
Content-Type: application/x-www-form-urlencoded
Request Body Parameters
token
- The token to revoke (required)
client_id
- Your client ID (required)
client_secret
- Your client secret (required)
curl -X POST https://api.sandbox.salvus-health.com/connect/revocation \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "token={token_to_revoke}&token_type_hint=access_token&client_id={your_client_id}&client_secret={your_client_secret}"
After revoking a token, you should request a new one using the standard token endpoint.
The base url depends on the envronment you want to use. For testing use sandbox environment, for real api calls use the production base url
https://api.sandbox.salvus-health.com
https://api.salvus-health.com