Skip to main content

Authentication and Authorisation

Authentication Overview​

The VIP API uses OAuth 2.0 to authorise requests with the platform.

Client Key & Secrets​

Your initial call will be to authenticate to receive and store a token. This call will need to pass your client_id and client_secret within the body

POST /oauth/token
Content-type: application/json
Body: client_id & client_secret

Example Request​

curl --location --request POST 'https://api.vetspace.cloud/oauth/token' \
--header 'Content-Type: application/json' \
--data-raw '{
    "client_id": "9VdO...rmi",
    "client_secret": "ZCR99c...Z-q4b"
}'

Example Response​

HTTP/1.1 200 OK
Content-Type: application/json
{
  "access_token":"eyJz93a...k4laUWw",
  "token_type":"Bearer",
  "expires_in":86400
}
Caching

Token reponse is cached for the duration of the token validity for your client key, use the expiry within the token and do not rely on the expires_in.

Scopes​

When the token is issued, it contains scopes which manage domains and groups of resources which you will be able to access. Your scopes may permit you access to GET a resource such as a patient, but you may be unable to, POST, PUT or DELETE on the same resource.

Access Tokens​

Tokens are issued for 1 day / 24 hour window and are valid to access all tenants, therefore you only need 1 token per day for all activities.

Record this token until expiry and use for all further endpoint calls.

Response Codes​

Below are the potential response codes for the oath/token endpoint.

200 - Accepted and token issued

400 - Bad request

401 - Unauthorised

403 - Forbidden

5xx - Error on Authentication Service

Calling an Endpoint​

Now you have your Bearer token we will use this along with the Tenant-Id header to access the data of the correct tenant.

Authorization: Bearer eyJz93a...k4laUWw
Tenant-Id: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Accept: application/json
info

You must supply these headers for every endpoint call in addition to any endpoint specific headers.

The API Explorer will not specify the authorisation requirments outlined here.

Tenants​

A tenant is a Veterinary Practice (Business) within the Veterinary Integration Platform, some Practices may be operating multiple tenants.

When we receive approval from a Practice for you to access their data, you will be provided with a Tenant-Id for that Practice, the Tenant-Id is in a UUID format. You will need to securely store this id for use within your application, it is not possible to query for tenants you have permission to access.

Example Request​

curl --location --request GET 'https://api.vetspace.cloud/contact-management/v1/api/contacts?page=1&size=2000&include-deactivated=false&default-location-uuid=f4616ac6-ce43-4971-b2dd-e25d1dd6580e&contact-type=User&last-name=smith' \
--header 'tenant-id: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
--header 'Authorization: Bearer ey...6-w' \
--header 'Accept: application/json'

Response Codes​

200 - OK

201 - Created - Used on a successful POST operation

400 - Bad Request

401 - Unauthorised - Your token may have expired or you do not have the required scopes.

403 - Forbidden - Your token may have expired or you do not have the required scopes.

404 - Endpoint not found - Check it exists or has not been deprecated.

5xx - Problem on our side.