Print Friendly and PDF
Follow

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.

APISecurityManager.png

Do not assign the "VETtrak, Trakker (System)" client access to any role in the "API VETtrak" application, if you have not changed its password to something more secure. The default password for this user is well known, so if you assign this user to an "API VETtrak" role without changing the password, you leave yourself open to the risk of malicious users using the API with the default credentials to obtain a wide range of data from your VETtrak database.

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:

Function Security rules
AddAward Protected
AddClassesToWebEnrolment Protected
AddClient Protected
AddClientAfterCheck Protected
AddClientEvent Protected
AddClientWebEnrolment Protected
AddClientWebReservation Protected
AddClientWebWaitlist Protected
AddContactToEmployer Restricted. Will only accept own employer identifier for the employerIdentifier parameter for employer users. Client users without API access cannot use this function.
AddEmployeeEnrolmentToBooking Protected
AddEmployer Protected
AddEmployerEvent Protected
AddEmployerWebEnrolment Protected
AddEmployerWebReservation Protected
AddLMSClientEnrolmentToOccurrence Protected
AddLooseWebEmployer Protected
AddPriceTypesToWebEnrolment Protected
AddUnitsToWebEnrolment Protected
AddWebEmployee Protected
AddWebEmployerContact Protected
AddWebInvoice Protected
AddWebPayment Protected
AddWebPaymentPlan Protected
API_Handshake Public
AssignWebEmployerToWebClient Protected
AssignWebEmployerToWebWaitlist Protected
CompleteWebReservation Protected
DB_Handshake Public
DeleteClientWebWaitlist Protected
DeleteLooseWebEmployer Protected
DeleteWebEnrolment Protected
DoesUsernamePasswordExist Protected
GetAccessibleClients Restricted. For users without API access, will only accept their own client code for clientCode parameter. Employers cannot access this function.
GetAccessibleDivisionsTree Restricted. For users without API access, will only accept their own client code for clientCode parameter. Employers cannot access this function.
GetAdditionalDataEntityNames Unrestricted
GetAdditionalDataFieldsForEntity Unrestricted
GetAdditionalDataForWebRecord Protected
GetAnzsicList Public
GetAPIVersion Public
GetAPIVersionComponents Public
GetAttendanceForClientClass Restricted. For users without API access, will only accept their own client code for clientCode parameter. Employers can access all clients.
GetAttendanceTypes Unrestricted
GetAwardsForClient Restricted. For users without API access, will only accept their own client code for clientCode parameter. Employers can access all clients.
GetAwardTypes Unrestricted
GetBookingDetails Unrestricted
GetBookingsForEmployer Restricted. Will only accept own employer identifier for the employerIdentifier parameter for employer users. Client users without API access cannot use this function.
GetClassesForClient Restricted. For users without API access, will only accept their own client code for clientCode parameter. Employers can access all clients.
GetClassesForOccurrence Unrestricted
GetClassesForStaff Restricted. For users without API access, will only accept their own client code for clientCode parameter. Employers can access all clients.
GetClientAVDetails Restricted. For users without API access, will only accept their own client code for clientCode parameter. Employers can access all clients.
GetClientByCode Restricted. For users without API access, will only accept their own client code for clientCode parameter. Employers can access all clients.
GetClientByEmail Protected
GetClientByName Protected
GetClientDetails Restricted. For users without API access, will only accept their own client code for clientCode parameter. Employers can access all clients.
GetClientExtendedDetails Restricted. For users without API access, will only accept their own client code for clientCode parameter. Employers can access all clients.
GetClientsForClass Protected
GetClientsForDivision Protected
GetClientsForHostEmployer Restricted. Will only accept own employer identifier for the employerIdentifier parameter for employer users. Client users without API access cannot use this function.
GetClientsForStaff Restricted. For users without API access, will only accept their own client code for staffClientCode parameter. Employers cannot access this function.
GetContractsForClient Restricted. For users without API access, will only accept their own client code for clientCode parameter. Employers can access all clients.
GetContractsForStaff Restricted. For users without API access, will only accept their own client code for staffClientCode parameter. Employers cannot access this function.
GetContractsOrEnrolmentsForClient Restricted. For users without API access, will only accept their own client code for clientCode parameter. Employers can access all clients.
GetCountryList Public
GetCourses Unrestricted
GetDeletedRecordsSince Protected
GetDisabilityList Public
GetDivision Protected
GetDivisionAncestors Protected
GetDivisions Protected
GetDivisionTree Protected
GetEducationHistory Restricted. For users without API access, will only accept their own client code for clientCode parameter. Employers can access all clients.
GetEmployeeEnrolmentsForEmployerEnrolment Restricted. Will only accept own employer identifier for the employerIdentifier parameter for employer users. Client users without API access cannot use this function.
GetEmployeesForEmployer Restricted. Will only accept own employer identifier for the sEmpl_Identifier parameter for employer users. Client users without API access cannot use this function.
GetEmployerAncestors Protected
GetEmployerContactDetails Restricted. Will only accept own employer identifier for the sEmpl_Identifier parameter for employer users. Client users without API access cannot use this function.
GetEmployerDetails Restricted. Will only accept own employer identifier for the sEmpl_Identifier parameter for employer users. Client users without API access cannot use this function.
GetEmployersForParentEmployer Restricted. Will only accept own employer identifier for the sEmpl_Identifier parameter for employer users. Client users without API access cannot use this function.
GetEmployerTree Restricted. Will only accept own employer identifier for the sEmpl_Identifier parameter for employer users. Client users without API access cannot use this function.
GetEmployerTypeList Unrestricted
GetEmploymentCategoryList Public
GetEnrolledTasksForClient Restricted. For users without API access, will only accept their own client code for clientCode parameter. Employers can access all clients.
GetEnrolledTasksForEnrolledUnit Restricted. For users without API access, will only accept their own enrolled units for the enrolmentId parameter. Employers can access all clients.
GetEnrolledTasksForEnrolment Restricted. For users without API access, will only accept their own enrolments for the enrolmentId parameter. Employers can access all clients.
GetEnrolledTasksForOccurrence Protected
GetEnrolledUnitsForEnrolledTask Restricted. For users without API access, will only accept their own enrolments for the enrolmentId parameter. Employers can access all clients.
GetEnrolmentsForClient Restricted. For users without API access, will only accept their own client code for clientCode parameter. Employers can access all clients.
GetEnrolmentsForOccurrence Protected
GetEnrolmentsForStaff Restricted. For users without API access, will only accept their own client code for sClie_Code parameter. Employers cannot access this function.
GetEventsForClient Restricted. For users without API access, will only accept their own client code for sClie_Code parameter. Employers can access all clients.
GetEventsForEmployer Restricted. Will only accept own employer identifier for the sEmpl_Identifier parameter for employer users. Client users without API access cannot use this function.
GetEventsForStaff Restricted. For users without API access, will only accept their own client code for sClie_Code parameter. Employers cannot access this function.
GetEventTypes Unrestricted
GetInvoicesForClient Restricted. For users without API access, will only accept their own client code for sClie_Code parameter. Employers can access all clients.
GetInvoicesForEmployer Restricted. Will only accept own employer identifier for the employerIdentifier parameter for employer users. Client users without API access cannot use this function.
GetLanguageList Public
GetLMSNewEnrolmentsForOccurrence Protected
GetLMSNewOccurrences Protected
GetLMSOccurrencesInDateRange Protected
GetLMSOccurrencesSince Protected
GetLocations Unrestricted
GetLooseWebEmployer Protected
GetOccurrenceDetails Unrestricted
GetOccurrenceExtendedDetails Unrestricted
GetOccurrencesForEmployer Restricted. Will only accept own employer identifier for the employerIdentifier parameter for employer users. Client users without API access cannot use this function.
GetOccurrencesForStaff Restricted. For users without API access, will only accept their own client code for staffClientCode parameter. Employers cannot access this function.
GetOrganisations Unrestricted
GetPaymentsForInvoice Protected
GetPaymentTypes Unrestricted
GetPositions Unrestricted
GetPricingForOccurrence Unrestricted
GetPriorEducationList Public
GetPriorEducationRecognitionList Public
GetProgrammes Unrestricted
GetProgrammeTypeList Unrestricted
GetQualificationAndCourses Unrestricted
GetQualifications Unrestricted
GetQualificationStateDetails Unrestricted
GetReferralSources Unrestricted
GetResultTypes Unrestricted
GetRooms Unrestricted
GetSchoolLevelList Public
GetSMSStatus Protected
GetStaff Protected
GetStaffExtendedDetails Protected
GetStaffForClient Restricted. For users without API access, will only accept their own client code for clientCode parameter. Employers can access all clients.
GetStaffForOccurrence Unrestricted
GetStaffForType Protected
GetStaffTypes Unrestricted
GetStateList Public
GetStudyReasonsForOccurrence Unrestricted
GetStudyReasonsForState Public
GetSuburbList Unrestricted
GetTasks Unrestricted
GetTasksForClient Restricted. For users without API access, will only accept their own client code for clientCode parameter. Employers can access all clients.
GetTasksForOccurrence Unrestricted
GetTaskStatuses Unrestricted
GetTraineeEventsForStaff Restricted. For users without API access, will only accept their own client code for sClie_Code parameter. Employers cannot access this function.
GetTraineesAndEmployeesForEmployer Restricted. Will only accept own employer identifier for the sEmpl_Identifier parameter for employer users. Client users without API access cannot use this function.
GetTraineesForEmployer Restricted. Will only accept own employer identifier for the sEmpl_Identifier parameter for employer users. Client users without API access cannot use this function.
GetUnitDetails Unrestricted
GetUnitsForClass Unrestricted
GetUnitsForContract Restricted. For users without API access, will only accept their own enrolments for the iCont_id parameter. Employers can access all clients.
GetUnitsForEnrolment Restricted. For users without API access, will only accept their own enrolments for the iEnro_id parameter. Employers can access all clients.
GetUnitsForEnrolmentIncludingLinked Restricted. For users without API access, will only accept their own enrolments for the iEnro_id parameter. Employers can access all clients.
GetUnitsForOccurrence Unrestricted
GetUnitsForQualification Unrestricted
GetUnitStateDetails Unrestricted
GetVisaTypeList Unrestricted
GetWaitlistProgrammes Unrestricted
GetWaitlistProgrammesForType Unrestricted
GetWaitlistProgrammeTypes Unrestricted
GetWebClientsForOccurrence Protected
GetWebEmployeesForEmployerEnrolment Protected
GetWebEmployeesForOccurrence Protected
GetWebEmployersForOccurrence Protected
GetWebEnrolment Protected
GetWebLocationsForProgrammeAndDates Protected
GetWebOccurrences Protected
GetWebOccurrencesForDates Protected
GetWebOccurrencesForProgramme Protected
GetWebOccurrencesForProgrammeAndDates Protected
GetWebOccurrencesForProgrammeAndDates Since Protected
GetWebOccurrencesOverlappingDateRange Protected
GetWebOccurrencesOverlappingDateRangeFor Programme Protected
GetWebProgrammes Protected
GetWebProgrammesForDates Protected
GetWebProgrammesForDatesSince Protected
GetWebProgrammesForProgType Protected
GetWebProgrammesForProgTypeAndDates Protected
GetWebProgrammeTypes Protected
GetWebProgrammeTypesForDates Protected
GetWebWaitlist Protected
IsEnrolmentComplete Restricted. For users without API access, will only accept their own enrolments for the iEnro_id parameter. Employers can access all clients.
ProcessWebEnrolment Protected
ProcessWebWaitlist Protected
QueryAdditionalData Protected
RecordPaymentForInvoice Protected
RemoveContactFromEmployer Restricted. Will only accept own employer identifier for the employerIdentifier parameter for employer users. Client users without API access cannot use this function.
SearchForEmployer Protected
SearchForSurname Protected
SearchWebOccurrences Protected
SendSMSMessages Protected
SendSMSMessageToNumber Protected
UpdateAdditionalDataForWebRecord Protected
UpdateAttendanceForClientClass Protected
UpdateClientAdditionalFields Restricted. For users without API access, will only accept their own client code for clientCode parameter. Employers can update all clients.
UpdateClientAVDetails Restricted. For users without API access, will only accept their own client code for clientCode parameter. Employers can update all clients.
UpdateClientDetails Restricted. For users without API access, will only accept their own client code for clientCode parameter. Employers can update all clients.
UpdateClientEvent Protected
UpdateClientTasks Protected
UpdateClientUsernamePassword Restricted. For users without API access, will only accept their own client code for clientCode parameter. Employers cannot access this function.
UpdateClientWebWaitlist Protected
UpdateClientWebWaitlistAVETMISS Protected
UpdateEmployerAdditionalFields Restricted. Will only accept own employer identifier for the employerIdentifier parameter for employer users. Client users without API access cannot use this function.
UpdateEmployerContactPrimary Restricted. Will only accept own employer identifier for the employerIdentifier parameter for employer users. Client users without API access cannot use this function.
UpdateEmployerDetails Restricted. Will only accept own employer identifier for the employerIdentifier parameter for employer users. Client users without API access cannot use this function.
UpdateEmployerEvent Protected
UpdateEmployerUsernamePassword Restricted. Will only accept own employer identifier for the sEmpl_Identifier parameter for employer users. Client users without API access cannot use this function.
UpdateEnrolledTask Protected
UpdateLMSEnrolmentStatus Protected
UpdateLMSOccurrenceStatus Protected
UpdateLooseWebEmployer Protected
UpdateResult Protected
UpdateResultComment Protected
UpdateResultIncludingLinked Protected
UpdateWebClient Protected
UpdateWebClientAVETMISS Protected
UpdateWebEmployee Protected
UpdateWebEmployeeAVETMISS Protected
UpdateWebEmployer Protected
UpdateWebEmployerContact Protected
UpdateWebEnrolment Protected
ValidateClient Public
ValidateEmployer Public
ValidateUser Public
ValidateUSI Unrestricted
Back to Top
    Tags:
  • api
Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.