Page tree
Skip to end of metadata
Go to start of metadata

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

Authorization endpoint

$base_url/oauth/authorize
Token endpoint$base_url/oauth/token
Token parameter nameaccess_token

Sample OAuth flow

The following steps provide you with a token for our demo site:

  1. 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).
  2. 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.
  3. 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: grant_type=authorization_code&client_id=test&client_secret=test&code=XXXXXX&redirect_uri=http://localhost. In a production environment, the client_id and client_secret should be replaced with your own client id and secret. The redirect_uri should match the value from the first step.
  4. 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.

Scopes

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.

  • No labels