Open the article in a separate window
The REST API allows access to and manipulation of all data held within the Timetabling Solutions dataset. Access is defined through a combination of application and user credentials, each granting access to specific data and is combined reductively to determine the effective permissions of the application-user combination.
Documentation
The RESTful API and its documentation are available at https://coreservices.timetabling.education/https://services.timetabling.education. Navigating this URL in a browser will open the API developer documentation, listing all calls, requests and response information.
The RESTful API and its documentation are available at https://coreservices.timetabling.education/https://services.timetabling.education. Navigating this URL in a browser will open the API developer documentation, listing all calls, requests and response information.
Authentication
Authentication with the API can be done using the standard Basic scheme; a valid session is also required to make API calls.
Each call to the service must include an Authorisation header that specifies the context of the request. This is done to slow down or prevent bad actors from sending requests to the API.
There are two types of Authorisation header: one used pre-authentication, which uses the app identifier and secret in your username and password fields, and one used post-authentication, which uses the authentication identifier (obtained as a response to authentication) and the app secret.
The authenticated request should use the pre-authentication header; the username and password fields are for a user account's credentials on the system. Each session is a combination of an app and a user; the effective permissions for the session are those that overlap between the app and the user. This means that a user won’t have their permissions elevated by logging into an app with higher privileges.
The response to the authenticated request will indicate the outcome of the attempt; only “Success” indicates the user was successfully authenticated. After this, you can use the authenticationIdentifier in the response to construct the post-authentication Authorisation header for other calls that require a session.
The Authorisation header should contain a standard HTTP basic authentication value. This document from the W3C has a definition of the basic authentication scheme, but essentially, you must concatenate the username and password with a colon between them, base64 encode this and append to the text “BASIC “. Below is a pseudo-code example:
Authorisation = “BASIC “ + base64(“username” + “:” + “password”)
Authentication with the API can be done using the standard Basic scheme; a valid session is also required to make API calls.
Each call to the service must include an Authorisation header that specifies the context of the request. This is done to slow down or prevent bad actors from sending requests to the API.
There are two types of Authorisation header: one used pre-authentication, which uses the app identifier and secret in your username and password fields, and one used post-authentication, which uses the authentication identifier (obtained as a response to authentication) and the app secret.
The authenticated request should use the pre-authentication header; the username and password fields are for a user account's credentials on the system. Each session is a combination of an app and a user; the effective permissions for the session are those that overlap between the app and the user. This means that a user won’t have their permissions elevated by logging into an app with higher privileges.
The response to the authenticated request will indicate the outcome of the attempt; only “Success” indicates the user was successfully authenticated. After this, you can use the authenticationIdentifier in the response to construct the post-authentication Authorisation header for other calls that require a session.
The Authorisation header should contain a standard HTTP basic authentication value. This document from the W3C has a definition of the basic authentication scheme, but essentially, you must concatenate the username and password with a colon between them, base64 encode this and append to the text “BASIC “. Below is a pseudo-code example:
Authorisation = “BASIC “ + base64(“username” + “:” + “password”)
When you’re creating the Authorisation header, use the values defined above for pre and post scenarios in place of the username and password.
Initialising a Session
To make stateful requests to the API, the client must first initialise a session by making a request to the https://services.timetabling.education/api/Authentication/Authenticate endpoint.
This call requires a basic authorisation token consisting of the Application Identifier and the Application Shared Secret.
e.g. [ApplicationIdentifier]:[ApplicationSharedSecret]
Subsequent Calls
Once a session has been instantiated, calls to other endpoints should use the Authentication Identifier instead of the Application Identifier in the basic authentication token.
e.g. [AuthenticationIdentifier]:[ApplicationSharedSecret]
Initialising a Session
To make stateful requests to the API, the client must first initialise a session by making a request to the https://services.timetabling.education/api/Authentication/Authenticate endpoint.
This call requires a basic authorisation token consisting of the Application Identifier and the Application Shared Secret.
e.g. [ApplicationIdentifier]:[ApplicationSharedSecret]
Subsequent Calls
Once a session has been instantiated, calls to other endpoints should use the Authentication Identifier instead of the Application Identifier in the basic authentication token.
e.g. [AuthenticationIdentifier]:[ApplicationSharedSecret]
Pricing: https://www.timetabling.com.au/shop
Free Tier: 5 calls per second, 40 calls per minute. 3 long (asynchronous) operations per hour and 10 in any 24-hour period
3rd Paid Tier = 10 calls per second, 60 calls per minute. File exports: 5 operations per hour and 20 operations in any 24-hour period. $999 + GST
2nd Paid Tier = 20 calls per second, 120 calls per minute. File exports: 8 operations per hour and 30 operations in any 24-hour period. $1,999 + GST
Top Paid Tier = 30 calls per second, 240 calls per minute. File exports: 20 operations per hour and 100 operations in any 24-hour period. $4,999 + GST
Planned for the next major release (2027)
OAuth 2.0 authentication
Webhook/event support