Skip to content

Latest commit

 

History

History
218 lines (147 loc) · 10.6 KB

OAuthApi.md

File metadata and controls

218 lines (147 loc) · 10.6 KB
Raw

uclapi.OAuthApi

All URIs are relative to https://uclapi.com

Method HTTP request Description
oauthAuthoriseGet GET /oauth/authorise Authorises a user against the API
oauthTokenGet GET /oauth/token A token will be generated which your app can use to get user’s personal data in JSON format from the OAuthSecurity/user/data.
oauthUserDataGet GET /oauth/user/data Returns personal data on a student at UCL.
oauthUserStudentnumberGet GET /oauth/user/studentnumber You can use the oauth/user/data endpoint to find out whether the user is a student before you call this endpoint. If you call this endpoint and the user is not a student, an error will be returned.

oauthAuthoriseGet

oauthAuthoriseGet(clientId, state)

Authorises a user against the API

This endpoint should be used to authorise a user against the API. It will perform a redirect if the user successfully logged in and accepted/denied the request. See the below code samples for how you might implement this in your code. Python: ```python url = "https://uclapi.com/oauth/authorise/?client_id=123&state=1\" ''' in a desktop app, script, or for testing ''' import webbrowser webbrowser.open_new(url) # note that you will also need some way receive the callback # this can be done via a web server (e.g. below) ''' on a Flask server this example covers both redirecting the user to the /authorise page and receiving the callback ''' from flask import Flask, redirect, request app = Flask(name) @app.route('/login') def uclapi_login(): return redirect(url) @app.route('/callback') def receive_callback(): # receive parameters result = request.args.get('result', '') code = request.args.get('code', '') state = request.args.get('state', '') # do something with these parameters # e.g. request an auth token from /oauth/token return ``` Shell: ```shell # linux xdg-open "https://uclapi.com/oauth/authorise/?client_id=123.456&state=1\" # WSL cmd.exe /c start "https://uclapi.com/oauth/authorise/?client_id=123^&state=1\" # note that you will also need some way to receive the callback ``` JavaScript: ```js const url = "https://uclapi.com/oauth/authorise/?client_id=123.456&state=1\" /* in-browser */ window.location.href = url // note that you will also need some way to receive the callback // this can be done via a web server (e.g. below) /* Node.JS Express server */ const express = require('express') const app = express() app.get('/login', (req, res) => res.redirect(url)) app.get('/callback', (req, res) => { const { result, code, state } = req.params // do something with these parameters // e.g. request an auth token from /oauth/token }) app.listen(3000) ```

Example

import uclapi from '@uclapi/sdk';

let apiInstance = new uclapi.OAuthApi();
let clientId = 9020633324528794.9923205739531139; // String | Client ID of the authenticating app.
let state = jAifrW3; // String | OAuth (random) state.
apiInstance.oauthAuthoriseGet(clientId, state, (error, data, response) => {
  if (error) {
    console.error(error);
  } else {
    console.log('API called successfully.');
  }
});

Parameters

Name Type Description Notes
clientId String Client ID of the authenticating app.
state String OAuth (random) state.

Return type

null (empty response body)

Authorization

No authorization required

HTTP request headers

  • Content-Type: Not defined
  • Accept: application/json

oauthTokenGet

InlineResponse2004 oauthTokenGet(clientSecret, clientId, code)

A token will be generated which your app can use to get user’s personal data in JSON format from the OAuthSecurity/user/data.

This endpoint should be used to obtain a token for use in the other API endpoints. See the below code samples for how you might implement this in your code. Python: ```python import requests params = { "client_id": "123.456", "code": "1", "client_secret": "secret", } r = requests.get("https://uclapi.com/oauth/token\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/oauth/token -d code=mysecretcode -d client_id=123.456 -d client_secret=secret ``` JavaScript: ```js fetch("https://uclapi.com/oauth/token?code=mysecretcode&client_id=123.456&client_secret=secret\") .then(response => response.json()) .then(json => console.log(json)); ```

Example

import uclapi from '@uclapi/sdk';
let defaultClient = uclapi.ApiClient.instance;
// Configure OAuth2 access token for authorization: OAuthSecurity
let OAuthSecurity = defaultClient.authentications['OAuthSecurity'];
OAuthSecurity.accessToken = 'YOUR ACCESS TOKEN';

let apiInstance = new uclapi.OAuthApi();
let clientSecret = "clientSecret_example"; // String | Client secret of the authenticating app.
let clientId = 9020633324528794.9923205739531139; // String | Client ID of the authenticating app.
let code = "code_example"; // String | Secret code obtained from the authorise endpoint.
apiInstance.oauthTokenGet(clientSecret, clientId, code, (error, data, response) => {
  if (error) {
    console.error(error);
  } else {
    console.log('API called successfully. Returned data: ' + data);
  }
});

Parameters

Name Type Description Notes
clientSecret String Client secret of the authenticating app.
clientId String Client ID of the authenticating app.
code String Secret code obtained from the authorise endpoint.

Return type

InlineResponse2004

Authorization

OAuthSecurity

HTTP request headers

  • Content-Type: Not defined
  • Accept: application/json

oauthUserDataGet

UserData oauthUserDataGet(clientSecret)

Returns personal data on a student at UCL.

Example

import uclapi from '@uclapi/sdk';
let defaultClient = uclapi.ApiClient.instance;
// Configure OAuth2 access token for authorization: OAuthSecurity
let OAuthSecurity = defaultClient.authentications['OAuthSecurity'];
OAuthSecurity.accessToken = 'YOUR ACCESS TOKEN';
// Configure API key authorization: OAuthToken
let OAuthToken = defaultClient.authentications['OAuthToken'];
OAuthToken.apiKey = 'YOUR API KEY';
// Uncomment the following line to set a prefix for the API key, e.g. "Token" (defaults to null)
//OAuthToken.apiKeyPrefix = 'Token';

let apiInstance = new uclapi.OAuthApi();
let clientSecret = "clientSecret_example"; // String | Client secret of the authenticating app.
apiInstance.oauthUserDataGet(clientSecret, (error, data, response) => {
  if (error) {
    console.error(error);
  } else {
    console.log('API called successfully. Returned data: ' + data);
  }
});

Parameters

Name Type Description Notes
clientSecret String Client secret of the authenticating app.

Return type

UserData

Authorization

OAuthSecurity, OAuthToken

HTTP request headers

  • Content-Type: Not defined
  • Accept: application/json

oauthUserStudentnumberGet

InlineResponse2005 oauthUserStudentnumberGet(clientSecret)

You can use the oauth/user/data endpoint to find out whether the user is a student before you call this endpoint. If you call this endpoint and the user is not a student, an error will be returned.

Please note: to use this endpoint you must have ticked the Student Number scope for your application in the Dashboard. This piece of information has been separated from the others because a student number can in some cases be considered confidential. This is because any data exported directly from Portico, SITS (E:Vision) or CMIS is usually grouped by Student Number. One example is that in some cases departments choose to release spreadsheets of examination results where each student is identified by their student number, and not their name, to provide a degree of anonymity in what is otherwise an open data set. You should consider carefully whether you actually need a student number to track students when other unique identifiers are available, such as their username-based email address and UPI. If you request a student number and it is not required for your application, your users may choose not to provide this information to you, and therefore deny your application permission to access their details.

Example

import uclapi from '@uclapi/sdk';
let defaultClient = uclapi.ApiClient.instance;
// Configure OAuth2 access token for authorization: OAuthSecurity
let OAuthSecurity = defaultClient.authentications['OAuthSecurity'];
OAuthSecurity.accessToken = 'YOUR ACCESS TOKEN';
// Configure API key authorization: OAuthToken
let OAuthToken = defaultClient.authentications['OAuthToken'];
OAuthToken.apiKey = 'YOUR API KEY';
// Uncomment the following line to set a prefix for the API key, e.g. "Token" (defaults to null)
//OAuthToken.apiKeyPrefix = 'Token';

let apiInstance = new uclapi.OAuthApi();
let clientSecret = "clientSecret_example"; // String | Client secret of the authenticating app.
apiInstance.oauthUserStudentnumberGet(clientSecret, (error, data, response) => {
  if (error) {
    console.error(error);
  } else {
    console.log('API called successfully. Returned data: ' + data);
  }
});

Parameters

Name Type Description Notes
clientSecret String Client secret of the authenticating app.

Return type

InlineResponse2005

Authorization

OAuthSecurity, OAuthToken

HTTP request headers

  • Content-Type: Not defined
  • Accept: application/json