Personal information in MyTimetable, like a user's subscriptions or personal timetable, is available after receiving an OAuth token for the specified user (or by using an elevated token, see API token).
MyTimetable uses OAuth version 2. More information on the OAuth specification can be found on the OAuth site, in the OAuth v2 RFC and in the OAuth v2 Bearer Token RFC. Currently, MyTimetable only supports the 'Authorization Code' grant type. This is because this is the only grant type that provides absolute client identification using a client secret. On request by the educational institution other grant types can be tested and enabled (but these types will provide less security).
For access to non-user specific resources (like the timetable of a room or module), a OAuth token will generally not be necessary, see Customer-specific API information for the exceptions.
OAuth endpoints and parameters
|Token parameter name|
Sample OAuth flow
The following steps provide you with a token for our demo site:
- Redirect the end-user to the following URL: https://demo.eveoh.nl/oauth/authorize?response_type=code&client_id=test&redirect_uri=http://localhost. The user is then asked to authenticated and grant the application permission to retrieve the user's personal information. Afterwards the user will be redirected to the
redirect_uri(so point this URL at your own web server).
- After granting permission, the user will be redirect to
redirect_uri/?code=XXXXXX. Using this authorization code and the client secret, your application will be able to request an OAuth token.
- In the background and from your own secure server, your application should make an HTTP POST request to https://demo.eveoh.nl/oauth/token with form-encoded parameters:
. In a production environment, the
client_secretshould be replaced with your own client id and secret. The
redirect_urishould match the value from the first step.
- This request will respond with an access token in JSON format. This token can then be used to do API calls by prepending the URL with
?access_token=token, or by providing an Authorization request header (e.g.
Authorization: Bearer XX-XX-XX-XX).
For optimal security, all communication should take place over an HTTPS encrypted channel. Also, the parameters in step 3 should be sent using an HTTP POST instead of GET. For more security recommendations check the RFCs.
Starting with MyTimetable 3.0, four scopes are available to limit an application's permissions, as follows:
username- read user information
user_read- read user information, including user name and roles (since 2019.21)
profile_read- read user subscriptions and user timetable
profile_write- edit user subscriptions
alltimetables- read any timetables the user has access to
messages_read- read any messages the user has access to (since 4.0)
If an authorization request is made without providing any scopes, all scopes allowed for your application will be requested. Scopes can be limited by using the
scope query parameter on the authorization request. In the authorization request dialog, the user will see a descriptions of the scopes your application wants to access.