Introduction
- Authorization
- Libraries and Examples
- Working with API
- Method Reference
  - adm_documents Info on administration documents
  - apiref Accessing API docs
  - apisrv API server data
  - apistlog Method call stats
  - attendance Attendance lists
  - blobbox Storing binary data
  - calendar University calendar
  - cards Data on users' ID cards
  - courses Info on courses
  - credits Study credits info
  - crstests Course tests
  - csgroups User-defined groups
  - emrex Student mobility
  - events Event subscriptions
  - events2 Manage events and notifiactions preferences
  - examrep Exam reports info
  - examrep2 Exam reports info
  - exams Registration for exams
  - fac Information on faculties
  - facperms Per-faculty permissions
  - feedback Feedback reports
  - fileshare Sharing files
  - geo Geographical data
  - grades Accessing grades info
  - groups Accessing group info
  - guide University guide
  - housing Dormitories and housing
  - instaddr Institutional addresses
  - mailclient Composing emails
  - mailing Sending email messages
  - meetings University meetings
  - mobility Access and edit Learning Agreement
  - news Faculty and university news
  - oauth OAuth Authorization
  - oauth2 OAuth provider module
  - payments Students' payments module
  - phones Phone numbers
  - photos User-photo settings
  - pit Access to PIT declarations
  - plctests Placement tests
  - prgroups Primary groups
  - progs Study programmes
  - registrations University registrations
  - slips Clearance slips
  - statements Signing statements
  - surveys Satisfaction surveys
  - terms Info on Academic Terms
  - theses Theses and diplomas
  - tt Accessing activity timetables
  - uprefs User preferences
  - users Accessing user information
- Contact us

Authorization

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.panschelm.edu.pl/services/oauth/request_token
Authorize URL: https://usosapi.panschelm.edu.pl/services/oauth/authorize
Access Token URL: https://usosapi.panschelm.edu.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.
1. 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.
2. 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.

USOS API ver. 7.1.0.0-4, 0e1fe7fc (2024-08-27)