OAuth Authorization
:: services/oauth module

This module contains the three OAuth entry points described in the Authentication section of this site. Note, that - strictly speaking - you (the Consumer) will use only two of them. The third one (the authorize method) is for the User to use. Your role is to (re)direct him to a proper URL only.

Methods

access_token Exchange authorized Request Token for an Access Token.
authorize Authorize the Request Token.
proxy Make a request with weakened permissions
request_token Get a new unauthorized OAuth Request Token.
revoke_consumer_key Revoke an existing Consumer Key.
revoke_token Revoke an existing Access Token

services/oauth/access_token

Consumer: required Token: required Scopes: none SSL: required
https://usosapi.awf.krakow.pl/services/oauth/access_token

Exchange authorized Request Token for an Access Token. Access Token can be used to access resources of a user who authorized the Request Token.

Standard OAuth "Consumer & Request Token" Authorization arguments are required.

Please note, that the returned Access Token MAY have access to more scopes than you declared in request_token method (but it will never have access to these scopes, which user hasn't granted your application access to).

oauth_verifier required Consult OAuth documentation for details.
Plus required standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Plus required oauth_token for Token authorization.

Returned value:

Standard OAuth 1.0a Token response - a string in a form-encoded format:

oauth_token=...&oauth_token_secret=...

You must be prepared that there might be more parameters returned in the future (you should ignore them gracefully).

services/oauth/authorize

Consumer: ignored Token: ignored Scopes: n/a SSL: not required
https://usosapi.awf.krakow.pl/services/oauth/authorize

Unlike other methods, the authorize method is to be executed inside the User's browser. Consumer's role is to redirect the User to the proper URL, then wait if he ever comes back with a callback request.

Once the User is redirected to this URL, several things will happen:

  • If he's not already logged in, he will be asked to log in.
  • USOS API will read the required scopes from the Request Token and check if the User haven't previously granted your application access for these scopes.
  • If User did not previously authorize your application, USOS API will display an "Authorization Request" form to the User. User will be presented with a choice to allow or not to allow your application access to his USOS account.
  • In either case, User's browser will be redirected to the callback_url you defined while getting your Request Token. If you did not provide a callback (or provided "oob"), user will be redirected to a default "authorized" page, where he will be presented with an oauth_verifier (called a PIN code) and asked to type it into your application.
oauth_token required Consult OAuth documentation for details.
interactivity optional

Default value: minimal

Currently, one of the following values:

  • minimal - we will use as little interactivity as we can. We will assume that currently signed-in user is the user which you want to authorize your app. If the user has already authorized your application, he will not be asked to do this again.
  • confirm_user - even if a user is already signed in, we will NOT assume that this is the "right" user. Use this if you suspect that your device might be used by multiple users. USOS API will offer the user to sign out and use a different account before he continues.

Please note, that USOS API uses external CAS servers for authentication. Each CAS server is maintained by different administrators (unrelated to the USOS API development team). Not all of them are configured to work in a user-friendly way. Hence, the authorization flow may work differently in different USOS API installations (especially when using confirm_user interactivity value).

No additional OAuth arguments are required. If you provide any, they will be ignored.

Returned value:

Technically, a HTTP 302 Redirect - it will direct user's browser to the apps authorization page.

Whether with callback_url or with a manual user entry - you will get your oauth_verifier, which allows you to continue the 3-legged authentication dance.

If you used callback_url, you should wait for a HTTP GET request, with additional GET parameters appended:

  • oauth_token - the Request Token that has been just authorized,
  • oauth_verifier - the PIN code required to get an Access Token.

services/oauth/proxy

Consumer: required Token: optional Scopes: n/a SSL: not required
https://usosapi.awf.krakow.pl/services/oauth/proxy

Make a method call with weakened permissions. This method is primarily intended for Administrative Consumers, but regular consumers may also find it useful.

Having "to much" permissions is not always a good thing. In many cases, you'd like the method to return only these results which your user has access to, not you. For example, if you are an Administrative Consumer and you try to access the email field of the user method, then you will always get the user X's email, even when the email should not be displayed to your user Y. However, if you repeat the same request via the the proxy method, then you will get the email only when your user is allowed to see it. In many cases this is exactly what you want!

In fact, we strongly encourage all Administrative Consumers to make all their requests via the proxy method.

The proxy method is also very useful when you're implementing a public AJAX proxy (e.g. if you're programming in JavaScript, or you use libraries like jQuery-USOS). Your users will be able to access their own personal data via your proxy, but they won't be able to access any private consumer-related data of yours (the exact definition of "private consumer-related data" is yet undocumented, but we try to use common sense; HTTP 400 error will be thrown when you try to access such data via the proxy method). Make sure your proxy is guarded against CSRF attacks!

From your point of view, this method will make the underlying method perceive your request as if it was made by a non-administrative, anonymous consumer with lower permissions:

  • If your request is an administrative one, then it will "stop being" administrative. That is, the underlying method will perceive it as a regular request. (This also means, that you can't call administrative methods via the proxy method.)
  • The list of scopes you've originally been given access to will be limited to the list provided in the scopes parameter.

Note, that if you're an Administrative Consumer, then you still can use the as_user_id parameter when calling the proxy method, but obviously you can't use it in the parameters dictionary (since you won't have the permissions to do so).

method required The name of the underlying method you'd like to call. Start with "services/".
parameters optional

Default value: {}

JSON-formatted dictionary of paramName-value pairs to be passed as parameters to the underlying method. All values should be unicode strings.
scopes optional

Default value: (none)

Pipe-separated list of scopes, or an extra keyword "all" to denote the set of all available scopes.

It is not an error to include scopes which you do not have access to. We will simply compute a common part (intersection) of your actual scopes and the scopes included here.

Since scopes are permissions granted by users, you must perform your request in a user context in order for this to work. You must supply either an Access Token or the as_user_id parameter.

Plus required standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Plus optional oauth_token for Token authorization.

Returned value:

We will return whatever response we get from the underlying method.

Note that currently, in case of an error, there is no simple way for you to determine which method caused the error to be thrown - the proxy method or the underlying method. However, the proxy method returns error responses only in quite obvious cases, so you should be fine.

services/oauth/request_token

Consumer: required Token: ignored Scopes: n/a SSL: required
https://usosapi.awf.krakow.pl/services/oauth/request_token

Get a new unauthorized OAuth Request Token. This token is bound to the Consumer it was issued to. It has a short expiration date and can be used in one way only - first it has to get authorized by the user, then it has to be exchanged for an Access Token.

oauth_callback required

An URI which you want a User to be redirected to after a successful Request Token Authorization (see "authorize" method). If the client is unable to receive callbacks, the parameter must be set to "oob", USOS API will provide a user with a PIN code in this case.

Also note, that some URI schemes are not allowed here for security reasons. If you're developing a mobile application and you want to use a custom scheme, then we advise you to use a scheme unique to your application (e.g. your Android package name).

Consult OAuth documentation for details.

scopes optional

Pipe-separated list of scope keys. Indicates your application requirements for User's resources access.

This is an USOS API specific argument, it is not part of OAuth standard. You should be able to use it along with existing OAuth libraries - just incorporate it into the base Request Token URL.

See here for the list of all available scope keys.

Please note, that the Access Token you receive in the end of this authorization process, will also allow you access all the scopes which the user has granted your application access in all previous authorization requests.

Plus required standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Token is not required.

Returned value:

Standard OAuth 1.0a Token response - a string in a form-encoded format:

oauth_token=...&oauth_token_secret=...&oauth_callback_confirmed=true

You must be prepared that there might be more parameters returned in the future (you should ignore them gracefully).

services/oauth/revoke_consumer_key

Consumer: optional Token: ignored Scopes: n/a SSL: not required
https://usosapi.awf.krakow.pl/services/oauth/revoke_consumer_key

Revoke (or begin the process of revoking) an existing Consumer Key. This might be useful after a Consumer Key was compromised.

There are two ways in which you can use this method:

  • You may call it without any arguments and sign it with the Consumer Key you want revoked, or:
  • Pass Consumer Key (and Secret) in plain text, as arguments.

Initially, this method allowed revoking Consumer Keys without the original owner's approval. Currently, only the owner may revoke the key. After you call this method, a message will be sent to the email address registered with the given Consumer Key. In order to complete the revoking process, additional action will be required.

consumer_key optional Consumer Key. Note: there is no oauth_ prefix.
consumer_secret optional Consumer Secret.
format optional

Default value: json

Format in which to return values. See supported output formats.
callback optional Required only if you've chosen jsonp as a return format.
Plus optional standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Token is not required.

Returned value:

{"success": true}. In case of error, expect HTTP 400 response (with the proper message field).

services/oauth/revoke_token

Consumer: required Token: required Scopes: none SSL: not required
https://usosapi.awf.krakow.pl/services/oauth/revoke_token

Revoke an existing Access Token. You need to sign your request with the Access Token you'd like revoked. You won't be able to use this Access Token after it's revoked.

Please note, that this does not sign out the user from USOS. It simply revokes a single Access Token. By default, the authorization consent is also preserved, so you are able to generate a new Access Token without the need for the user to log in and authorize your app again.

deauthorize optional

Default value: false

BETA Set this to true if you want not only to revoke the given Access Token, but also revoke all Access Tokens bound to your Consumer Key and all saved authorization data for your Consumer Key.

Please note, that the preferred way of deauthorizing apps is refering the user to the USOSapps main page.

Plus required standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Plus required oauth_token for Token authorization.

Returned value:

{"success": true}, or a HTTP 400 response in case of error.

USOS API ver. 7.0.2.0-0, 7234c49e, dirty (2024-02-26)