Crest of the Australian Government Unique Student Identifier-Logo

System developers – USI Registry System support and information

We provide information and support to help software developers integrate with the USI Registry System via web services. For more information, contact us at IT@usi.gov.au

To establish web service connections, the USI Registry System uses a combination of an organisation’s ABN and USI OrgCode for authentication and authorisation.

Software Developer Kits

Developers need:

USI Developer Kit

The USI Developer Kit includes:

  • USI web service technical services contract
  • current version of the security token service – service definitions
  • USI check character algorithm
  • connection instructions
  • Machine-to-Machine (M2M) authentication and organisation codes for the test environment.

Apply for the USI Developer Kit (DK)

Connecting to the USI Registry System

When accessing the Registry System, an organisation is authenticated. The OrgCode is submitted to the USI Registry System and checked that it:

  • is registered in the USI Registry System
  • has an ABN that matches the certificate generated from authentication credentials
  • has been authorised by the Student Identifiers Registrar to use the USI web services
  • is the correct organisation type (Registered Training Organisation, VET related body, Higher Education Provider or Tertiary Admission Centre) to use the called functions.

For more information, contact us at IT@usi.gov.au.

Obtaining Machine-to-Machine (M2M) authentication

Web services use Machine-to-Machine (M2M) authentication. To be issued with M2M, an organisation and its staff must first set up a myGovID and Relationship Authorisation Manager (RAM).

Authentication options

Desktop software

Organisations download software to their own environment and use their secure M2M credential for transactions to the USI Registry System.

Cloud software

The My Cloud software services allows software developers to design and install a solution for clients using cloud-based SBR enabled software. This enables secure communication with the Office of the Student Identifiers Registrar.

An organisation using cloud-hosted services does not have to get their own M2M credential. The digital service provider is required to create a machine credential and install it on their server. The digital service provider is then able to authenticate a connection to the USI Registry System by third party users.

After obtaining a Digital Identity and claiming their business in Relationship Authorisation Manager (RAM), the business associate of an organisation needs to access RAM and nominate the digital service provider submitting transactions on their behalf.

To use USI web services in the production environment, an education or training provider must be authenticated and authorised to access the USI Registry System and meet the following requirements:

  • registered training organisations must be listed on training.gov.au (TGA)
  • higher education providers must be listed on the TEQSA National Register.

The USI Registry System uses the education or training provider ABN and code details as listed on TGA or the National Register for authentication purposes. The ABN listed must be the same one linked in RAM and registered with the Australian Business Register. If an education or training provider has changed their ABN recently, they need to update their details on TGA or the TEQSA National Register.

Where organisations have a single ABN and multiple organisation codes (including dual sector providers) Machine-to-Machine credentials can be used.

All education or training providers must:

  • have a Student Management System that has incorporated the USI Technical Services Contract
  • have Machine-to-Machine (M2M) credentials installed in their SMS infrastructure. To be issued with M2M, an organisation and its staff must first set up myGovIDs and Relationship Authorisation Manager (RAM)
  • complete the System Access Request Form to request access to use USI web services and accept the terms and conditions of use.

An access form needs to be submitted for each provider, as defined by organisation codes, requesting access to web services and accepting the terms and conditions of use.

Organisations must read and understand the terms and conditions of using the USI Registry System.

Other VET related organisations and Tertiary Admission Centres wishing to use USI web services must:

  • set up myGovIDs and RAM
  • have M2M credentials
  • complete the System Access Request form so they can be issued an USI organisation code which must be supplied as a part of all USI web service calls
  • agree to the terms and conditions of use.

Student Management System (SMS) developers must use our third party environment to test their system for:

  • web service authentication
  • connectivity
  • functionality.

To arrange access to our third-party testing environment, complete the USI Developers Kit application form.

Once approved, you will be issued with the USI Developers Kit which includes:

  • USI web service technical services contract
  • current version of the security token service – service definitions
  • USI check character algorithm
  • connection instructions
  • Machine-to-Machine (M2M) authentication and organisation codes for the test environment.

Using libraries in development is required

  • WCF for .NET (latest versions, minimum requirement .NET 4.5)
  • Java WSIT library (authorised by Microsoft and Sun and published on the Oracle website)

Web services integration

We have developed a web services component that enables calls between Student Management Systems (SMS) and the USI Registry System.

The services allow an authorised consumer to:

  • create a USI record for an individual and receive an immediate response
  • submit a batch of USI creation requests for processing
  • retrieve the results of a previously submitted batch request
  • verify a USI for an individual and receive an immediate response
  • verify a batch of USIs and receive an immediate response.

USI Technical Services Contract and web service versioning policy

To set up web service functionality, along with other details, you will need the USI Registry System Technical Services Contract in conjunction with the policy and procedures for web service versioning for the USI Registry System. The current version of the Technical Services Contract (TSC) is V 4.0, effective September 2020, however organisations can continue to use V 3.0, until 2 November 2021

All new systems must use Technical Services Contract Version 4.0 from September 2020.

USI Organisation Portal users

Read about minimum system requirements for myGovID and RAM.

DotNET Framework

Organisations experiencing problems with specific machines may resolve the machine issue by having dotNET Framework reinstalled (and/or upgraded from 4.0 to 4.5 on machines that won't connect).

Student Management System (SMS) error messages

Organisation was not verified as an authorised body/organisation in the system

The error indicates the organisation has not requested access to the USI Registry System using web services or if access has been requested, the application has not yet been processed.

A request for access via web services and accepting terms and conditions is a mandatory requirement.

An error occurred when verifying security for the message

In the USI request, all the EncryptedData elements (including the EncryptedAssertion element) need to appear before all instances of the Signature element.

Some developers have resolved the issue by changing the order of the classpath parameters for the java execution.

ID3242: The security token could not be authenticated or authorised

ATO MAS gateway does not authenticate using a username/password model. It uses a certificate. If a developer uses the svcutil tool against the endpoint they will generate a config file which shows the bindings expected. They should see that a certificate is required, not a password.

Unknown KeyStore exception – 4699

For applications developed in .Net using IIS manager. In IIS Applications Pool -> Advanced Settings:- changing the setting ‘Load User Profile’ to true solved problems for some users.

If not using .Net/IIS manager, this solution (amending local settings) may be something that can be investigated.

The relying party specified in the ‘Applies to’ element is not recognised. Event Code [E2044]

This error is encountered when code has been migrated from the test environment into the production environment. To resolve this, remove:

  • any references to the 3PT realm in the 'Applies To' element of the request to the production Security Token Service (STS) at VANguard
  • any testing references (for example ‘3PT’ or ‘third party’) from all endpoint production URLs.

Could not establish trust relationship for the SSL/TLS secure channel with authority 'authentication.softwareauthorisations.ato.gov.au’

TLS protocol 1.2 is the minimum version supported in the USI Registry System. Check whether a 2003 server that is not compatible with USI Web Services is being used.

I am testing the system but it says the credential has expired

Send a request for an updated credential file to IT@usi.gov.au.

What do I need to be able to test my system connectivity with the USI Registry System?

Register for web services testing with the USI Developer Kit (DK) request form. 

What happens after I submit my USI Developer Kit (DK) form?

You will receive the USI Developer Kit which contains everything that is needed to connect to USI web services, including:

  • test environment credentials and org codes
  • checksum algorithm
  • technical service contract.

The USI Registry System provides a web service to allow authorised education or training providers to initiate direct, system-to-system interactions with the USI Registry System.

The web service versioning policy is intended for:

  • the USI Registry System Development team
  • the USI Registry System Operations team
  • system developers (usually Student Management Systems) that consume the USI Registry System Web Service.

Read the web service versioning policy.

Does a cloud solution include the SMS? The SMS is the only cloud based software we use.

Yes, it does if you are using a cloud-based Student Management System (SMS) and have shared your Machine-to-Machine credentials with your SMS provider to enable you to use that software.

The My Cloud software service allows education or training providers to:

  • notify the government of their cloud-based software provider
  • securely transact with the USI Registry System without the need for their own Machine-to-Machine credentials.

What is the USI Developer Kit (DK)?

The USI Developer Kit is provided by the Office of the Student Identifiers Registrar and contains everything that is needed to connect to USI web services, including:

  • test environment credentials and org codes
  • checksum algorithm
  • technical service contract.

What is the Technical Service Contract (TSC)?

The TSC is a set of codes that can be consumed by the organisation's Student Management System to use the USI Registry System web services component. 

What is a machine credential?

Machine-to-Machine (M2M) credentials are used for system to system web services and installed on the server hosting an education or training provider’s system. M2M credentials identify a business rather than a person. Users of a USI web service enabled Student Management System (SMS) do not need their own individual credential.

M2M credentials are used in third party testing (3PT) and production environments.

The Office of the Student Identifiers Registrar provides credentials for third party testing.

Production credentials are created by the authorised person in the education or training provider through the ATO RAM system.

What are the end point URL’s for the USI System?

Section 4.2.2 of the USI Technical Services Contract (TSC) identifies the complete range of production URLs.

What is the 3PT machine credential password?

The machine credential case sensitive password for 3PT is: Password1!

Was this page helpful?

If you need help, please call us on 1300 857 536 or from outside on Australia +61 2 6240 8740. Our contact centre is open between 8.30am-5:00pm (Australian Central Standard Time), Monday to Friday (excluding national and South Australian public holidays).

OR

If you would like to provide feedback, please complete the feedback form.

Office of the Student Identifiers Registrar (OSIR)
Last Modified on Friday 15th October 2021 [117]