|
OAuth Authorization
|
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 ¶
|
||||||
https://usosapps.us.edu.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 ¶
|
||||||
https://usosapps.us.edu.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:
| ||||||
oauth_token | required | Consult OAuth documentation for details. | ||||
interactivity | optional |
Default value: minimal Currently, one of the following values:
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:
|
services/oauth/proxy ¶
|
||||||
https://usosapps.us.edu.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:
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 ¶
|
||||||
https://usosapps.us.edu.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 ¶
|
||||||
https://usosapps.us.edu.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:
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:
|
services/oauth/revoke_token ¶
|
||||||
https://usosapps.us.edu.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 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:
|