Normally, an API token is required to access the MyTimetable API. For OAuth authorisation, an client id and secret are necessary. This document describes how these API and OAuth access tokens can be managed by an administrative user.

All tokens can be managed directly in the MyTimetable user preferences database. This can be done using a SQL client application, like Microsoft SQL Server Management Studio. Currently, there is no administrative (web) interface to configure OAuth tokens. Some settings and changes may be cached for 5 minutes.

API tokens

API tokens can be managed through the MyTimetable administrative interface.

In case the administrative interface is not available, API tokens can be found in the table api_tokens. The following list describes the columns of this table:

nameDescription of the application, only used for administrative and logging purposes.
tokenToken the application should use in its requests.
is_elevatedtrue if the token should be allowed to impersonate any user (without separate OAuth permission). false otherwise. Setting this value to true is only recommended for applications that can be fully trusted with all user information.
authentication_requiredtrue to require an OAuth token to be present in requests using this API token

OAuth information

To use the OAuth authorisation options in MyTimetable, an application requires an client id and secret. These can be entered in the table oauth_client_details. A client should provide its client id and the web server redirect URL. The following list describes the columns of this table:

client_idThe client identifier. Shown in the MyTimetable web interface and used by the OAuth client to identify itself. Should consist of only characters in the range [A-Za-z0-9].
resource_idsThe resources a client can access, comma-delimited. Not used by MyTimetable, enter NULL.

The secret a client uses to identify itself. This is specified as a Spring Security hash. Possible options:

{SHA-256}<sha256 hash of password>

SHA-256 hashed password. Recommended if the password has enough entropy in itself (e.g., 32 random characters or more).
{bcrypt}<bcrypt hash of password>Bcrypt hashed password. Required if the password has low entropy. May have a performance impact if many OAuth authorisations take place.
{noop}<password>No hashing. Not recommended.
scopeThe scopes a client can request, comma-delimited. Choose from the following list (comma-separated): username,profile_read,profile_write,alltimetables
authorized_grant_typesGrant types the client can use. MyTimetable only supports the authorization_code grant type, so enter authorization_code.
web_server_redirect_uriThe URL that should be used by the client to receive the access code. This must exactly match the redirect_uri used by the client. Strongly recommended to use HTTPS URLs.
authoritiesAuthorities of the OAuth client. Not used by MyTimetable, enter NULL.
access_token_validityTime an OAuth token will be valid, in seconds. 0 for an non-expiring token.
refresh_token_validityRefresh tokens are currently not supported by MyTimetable, enter NULL.
additional_informationAdditional information can be entered in this field. Currently, this information is not used by MyTimetable, enter NULL.
autoapproveList of scopes to automatically approve, or true to approve all scopes.
  • No labels