VETtrak API Security Changes for VETtrak 18.1

Introduction

To better protect access to VETtrak data, security rules across the entire API have been tightened in version 1.16 of the VETtrak API, which has been released alongside VETtrak 18.1 in January 2018.

These changes will likely impact existing third-party applications that are using the API to integrate with VETtrak. The changes do not affect most VETtrak-produced integrations such as VETsurvey, VETnet, Trainer Portal, Student Portal, VTDocs and Progress Portal, but VETenrol is affected by the changes.

For VETtrak administrators

After upgrading to VETtrak 18.1, to continue to use the API, you must have a new "VETtrak API" feature in your VETtrak registration key. To update your registration key, in VETtrak, go to the File menu -> Global Preferences -> Registration key -> Update Key Automatically button. If this is not done, the following error will occur when calling nearly every API function: The registration key does not contain a valid registration for the "VETtrak API" feature. In VETtrak, go to the File menu -> Global Preferences -> Registration Key to view the registration information, and press "Update key automatically" to update it. Contact VETtrak Support if you need to obtain a valid registration for this feature.

In the Security Manager in VETtrak, a new "API VETtrak" application will then be available. This contains a role called "VETtrak API default role" that has access to the new "VETtrak API" feature. Only users who you have explicitly granted access to this role will be able to access all functionality in the VETtrak API. All other users will only be able to access less sensitive parts of the VETtrak API functionality. Note that only clients marked as staff members can be granted access to the "API VETtrak" application. The existing "API Functions" feature is still used to control which users can access API-related functionality (publish occurrences, process web enrolments etc) in the VETtrak desktop application.

For most types of integrations, you will need to assign one user to the "VETtrak API default role" in the Security Manager. This user should have a secure password. If you don't already have an appropriate client to use for this, then you should create a new one solely for this purpose. You will then configure your integration to use this username and password when calling the VETtrak API. Doing this will limit full access to the API to just this one user.

If you are using the VETenrol product, you may stop here, as the rest of this article is not relevant. Developers of third-party products that use the API to integrate with VETtrak will need to review the technical information provided in the rest of this article.

For third-party developers

Each function in the API has been put into one of four security categories:

Public

Functions in this category are accessible to anyone, not requiring a token. The methods that are in this category were already publicly accessible in previous versions of the VETtrak API and have not changed in this version. These functions only return data that is publicly available and included by default in the VETtrak database (such as retrieving a list of valid school levels).

Unrestricted

Functions in this category will require a token to access, but will not require explicit access to the "VETtrak API" feature to order to utilise them. These are functions which do not deal with particularly sensitive information. They work the same as they did in previous versions of the VETtrak API, meaning all authenticated users can always access them.

Restricted

Functions in this category will require a token to access, but will offer limited functionality if the user is not granted access to the new "VETtrak API" feature. This will involve restricting the permitted input parameters to prevent access to data that the user should not have access to. For example, a client who has not been granted access to the "VETtrak API" feature can use functions to only access their own data (and only in some cases – for example, clients cannot alter their own unit results, etc.). Users who have been granted explicit access to the "VETtrak API" feature will not be subject to any restrictions placed on these functions and will be able to read or alter any data as applicable to the function as per previous versions of the VETtrak API.

Protected

Functions in this category will require a token to access, and require the user to be explicitly granted access to the "VETtrak API" feature to be used. These are functions which deal with sensitive data or are impractical to restrict to a particular user's data. Only users who have been granted access to the "VETtrak API" feature in the Security Manager within the VETtrak software will be able to call these functions as per previous versions of the VETtrak API.

A new Status of -6 (InsufficientAccess) is returned by the API in TAuthenticate to indicate that the user does not have sufficient access to call the function. The message will indicate the reason, such as:

• Client login calling a protected function when they do not have access to the "VETtrak API" feature: You do not have access to this protected API function. To access this function, in the VETtrak Security Manager, the user needs to be assigned access to an active role in the "API VETtrak" application.
• Client login calling a restricted function with a parameter that is not themselves: You can only access your own data using this restricted API function. For full access to this function, in the VETtrak Security Manager, the user needs to be assigned access to an active role in the "API VETtrak" application.
• Client login calling a restricted function that is only available to employers: This restricted function cannot be accessed by client logins. For full access to this function, in the VETtrak Security Manager, the user needs to be assigned access to an active role in the "API VETtrak" application.
• Employer login calling a protected function: This protected function cannot be accessed by employer logins.
• Employer login calling a restricted function that is only available to clients: This restricted function cannot be accessed by employer logins.
• Employer login calling a restricted function with a parameter that is not themselves: You can only access your own data using this restricted API function.

If you always authenticate to the API with one account (which would be the case in most online enrolment and LMS integration scenarios), you simply need to add that client to the "VETtrak API default role" role in the Security Manager, and you can continue using the API as you always have. If you authenticate to the API with wide range of accounts that are entered by users (for example, client or employer logins, in student or employer portal scenarios), for security and practicality reasons you should not add all these users to the "VETtrak API default role". Instead, you will need to analyse the impact to your product and make changes as appropriate. Some functions can be used by the user's token, but if you need to access protected functions, or restricted functions with other parameters, you may need to use ValidateClient to establish another session and token for a specific client with access to the "VETtrak API default role" and use this when calling those sensitive API functions.

To allow time to make any necessary changes to your product, it is possible to continue using the VETtrak 17.3 version of the API (version 1.15.0.0) with a VETtrak 18.1 database in the meantime.

The following lists the security category that applies to each API function: