USOS API uses OAuth 1.0a protocol for authorization.
There are lots of good articles over the Internet which explain OAuth
nicely. Try reading some of them before you continue.
For example:
Overview
You probably know the model that powers Facebook/Twitter/Google apps:
- There are plenty of applications for Facebook users to pick from.
All of them need access to user data in order to work properly.
- When user clicks an application, Facebook asks him if he is willing
to give the application his permission to access certain resources and/or
perform certain actions.
- When user agrees, he's redirected to the application webpage and the
application itself can now access user data through Facebook API.
This model is powered by OAuth - a standard method of secure API
authorization for web/desktop*/mobile* applications.
* - Please note, that if you plan to publicly deploy a desktop/mobile
application, then your OAuth Consumer Key might be compromised. Secrets might be
stolen. Consider using your own server-side proxy.
Entry points
If you already know OAuth, these three URLs should be all you need:
- Request Token URL: https://usosapi.awf.krakow.pl/services/oauth/request_token
- Authorize URL: https://usosapi.awf.krakow.pl/services/oauth/authorize
- Access Token URL: https://usosapi.awf.krakow.pl/services/oauth/access_token
Please note:
- There are multiple USOS API installations which use different URLs.
Try to make your application work on all installations.
- The services/oauth/request_token
method has some extra non-standard parameters you will probably want to use.
OAuth 1.0a workflow
There are plenty of OAuth guides and libraries over the web so we
won't be diving into the technical details, we will only sum up how OAuth
works from the developer's perspective.
There are three players in this scene, so be aware which is which:
- Application - also called a Consumer, this is the
piece of code you're building.
- USOS API - also called a Provider, this is us :)
- User - this is always one of USOS users who interacts
with your application.
Here's what happens:
-
First, you generate an API key
for your application. This consists
of two strings of random characters called a Consumer Key
and a Consumer Secret.
Having these two, you are now able (using OAuth client libraries)
to make a signed "2-legged" API call. (This is called "2-legged",
because there is no User on the scene yet - if there was, we'd call it
a "3-legged" call.)
- You can make 2-legged USOS API calls having the Consumer Key only, but
surely you'll want more complex API methods, which require Users to share their data with you.
Here's where the 3-legged authentication begins.
- A User connects to your site. You want him to share his data with you.
You make a 2-legged services/oauth/request_token
API call to acquire a Request Token and Request Token Secret.
You MUST provide an oauth_callback and MAY provide scopes
parameter at this stage (see here). These will affect
the authorization flow below.
- You generate USOSapps authorization URL and ask your
User to visit it.
- User visits the authorization page. (If he's not logged in, USOS API
will first ask him to log in.) User will be asked to share his data with
a screen similar to the one below. What a User will see on this screen
is strongly affected by the scopes you declared in the previous step.
-
User grants access to his private data. Now your Request Token
becomes an Authorized Request Token, which is bound to the
User who was logged in and authorized it.
- If you have supplied a callback URL (non-oob value)
while generating authorization URL above, User's browser is
redirected to this URL. USOS API will append a PIN code
(OAuth Verifier) to the URL GET parameters, where you (Consumer)
can easily read it.
- If you haven't (oauth_callback=oob), USOS API will
display a PIN code to the User. Your application will have to
ask the User to enter it manually.
- In either case, now you have an Authorized Request Token (bound to
a specific User) and a PIN code. You will use them to acquire an
Access Token.
-
You make a "3-legged" services/oauth/access_token
API call signing it with your Consumer Secret and Request Token Secret (note: later you will use Consumer Secret
and Access Token Secret for all "3-legged" API requests).
In exchange you receive an Access Token and Access Token Secret.
-
Now you may use Access Token (along with your Consumer Key) to
call User-related API methods.
Token expiration issues
OAuth tokens may expire. What is USOS API's policy on token expiration?
As you may expect, Request Tokens expire quickly. You should not assume that they will be valid
for longer periods of time than say, half an hour. Request Tokens are intended to be
immediately exchanged for Access Tokens.
Currently, Access Tokens expire after two hours OR after user logs out.
Note, that all Access Tokens become invalidated after a User revokes access
to his USOS account from your application. Users can remove applications using
their USOSapps Administration Panel.
If you need a long-lived Access Token, you may get one by asking for
an "offline_access" scope.
Scopes
When you request a Request Token, you may pass the scopes parameter,
which describes the things you want the User to share with you. Many API methods
require you to have the access to multiple scopes.
When you ask a User to authorize your Request Token, USOS API will
notify the User which scopes your application requires. Choose wisely -
users may discard your request if you want too much!
Currently available scope keys:
-
What you get by default:
Permission to read basic user information (such as user's
name and ID). You don't need to request this permission
explicitly - you receive it by default with each Access Token.
-
adm_documents:
Allows access to get administration documents etc.
-
cards:
Provides access to user's ID cards data, such as chip uid or expiration date
-
change_all_preferences:
Allows you to change user preferences (via the uprefs module). You
may need some other scopes in order to change or view some of the
preferences. Also, the access to some important preferences may be
restricted in other ways, i.e. only Administrative Consumers may
be allowed to change them.
-
crstests:
Provides access to details and results of user's course tests.
-
dorm_admin:
Provides access to administrative housing operations on user's
behalf. For more information, please visit the housing module.
-
edit_user_attrs:
Allows editing user's attributes (the same thet the user can edit
on his USOSweb profile page).
-
email:
Provides access to user's email address.
-
events:
Allows access to user's preferences, push notifications, etc.
-
grades:
Provides access to grades information.
-
grades_write:
Allows access to read and write exam reports.
-
mailclient:
Provides access to the mailclient module (in the name of your
user). Currently only a small set of methods is available for
non-administrative consumers, but this set will be growing.
-
mobile_numbers:
Provides access to user's personal mobile phone number(s).
-
offline_access:
Enables your application to perform authorized requests on behalf
of the user at any time. By default, Access Tokens expire after a
short time period to ensure applications only make requests on behalf
of users when they are actively using the application. This scope
makes Access Tokens long-lived.
-
other_emails:
Provides access to email addresses of other users (i.e. the ones
related to your user).
-
payments:
Allows access to your payments.
-
personal:
Provides access to user's personal data, such as PESEL number,
date of birth, etc.
-
photo:
Provides read access to user's photo and his/her photo visibility
preferences ("who can see my photo?").
-
placement_tests:
Provides access to results of user's placement tests in foreign languages.
-
session_debugging_perms:
(for Administrative
Consumers only)
Allows access to official permissions related to the user's session
debugging rights. Allows you to get the answer to the question "Is
my user permitted to debug the session of user X?". See
"can_i_debug" field of the services/users/user method for more
information.
-
slips:
Provides access to most of the actions within the Clearance Slips
module. With this scope you can view, create and edit slips, answer
questions and perform any non-administrative action which the user
can perform via USOSweb. You will need an additional 'slips_admin'
scope if you want to manage slip templates too.
-
slips_admin:
Provides access to template management of the "slips" module. That
is, it allows you to create and edit questions, mark templates as
obsolete etc.
-
staff_perspective:
If your user is a staff member, then this scope provides access to
some common student-related data usually visible only to staff
members, e.g. student numbers, or broader lists of students' study
programmes.
-
student_exams:
Provides access to lists of student's exams, information on
their examiners, places the exams take place etc.
-
student_exams_write:
Allows to register and unregister the student from his exams.
-
studies:
Provides access to lists of programmes, courses, classes
and groups which the user attends (as a student).
-
surveys_filling:
Allows access to surveys from students point of view.
With this scope you can fetch and fill out surveys.
-
surveys_reports:
Allows access to reports on surveys that concern user as a lecturer.
-
theses_protocols_write:
Allows access to editing diploma exam protocols, e.g. signing protocols.
Administrative Consumer Keys
There are some API services, that allow access to data that is
not available to normal users. Therefore, there is no user, that
could authorize access to such data - the access scopes policy
described earlier does not apply.
In order for you to access such sensitive data, you will need to
contact
USOS API administrators directly. Describe which methods you want
to use and why. If all goes well, you will be provided with an
Administrative Consumer Key (and Secret).
You can use your Administrative Consumer Key just like an ordinary one,
but you will also have an administrative access to some of the methods.
This means, that you may execute standard user methods with a as_user_id
parameter (instead of a valid Access Token), plus you might get access
to methods that are not usually available to ordinary developers.
Probably you won't even need to do all of the 3-legged OAuth
dance, since you will be able execute a set of methods directly, without
a need for user's consent.