GETMARKED Connect

Overview
GETMARKED Connect is a set of 2 facilities -- Item Bank Connect and User Connect.

Item Bank Connect allow common users between GETMARKED and the partner app to leverage their GETMARKED question banks in those partner apps, and User Connect allow GETMARKED users to Single Sign-on (SSO) into a partner app.

GETMARKED Item Bank Connect

Item Bank Connect allows you to access questions data from a user common to both of us for use in your own app. Questions data from this facility requires user authorization and user will initiate and select the questions that they want to send to your app.
GETMARKED will essentially act as an external question bank that our common user can tap upon. Your app can then focus on the delivery and utilization of those data.
The entire flow of this process starts with your app redirecting a common user to GETMARKED for authorization. Once authorization is completed, we will send the questions data to you and then redirect the user back to your site.

App registration

To start, please register your app using a developer account with us first. We would need the following information:
  • App Name
  • App Description
  • App Domain
App Name and App Description are user facing. App Domain will be the only domain we will interact with. This registration is subject to approval. We will reach out through email to arrange for a meeting. Once approved, you would be able to start using this facility.

Step 1: GET a auth_url


http://digitaliser.getmarked.ai/partner_apps/item_bank/user/connect/setup?data_url=...&success_url=...&cancel_url=...&secret=...
Please send a HTTP GET request to the endpoint above, you will get back a JSON containing the auth_url which you should redirect your user to. Your GET request should include the following query string:
  • secret
  • data_url
  • success_url
  • cancel_url
secret will be generated once you register your app. It is how we know the request came from your app and must be kept secret. Do not launch this request from client side. data_url is where we will send the questions data to. It will be a HTTP POST request with the request body containing the JSON data of the user selected questions. If a response with status code of 2XX is returned from the POST request, we will redirect user to success_url else we will redirect the user to cancel_url. If user decide to terminate the process we would also redirect user back through cancel_url. 

{
    "status": "success",
    "message": "Connection allowed.",
    "data": {"auth_url": "https://URL_TO_REDIRECT_USERS_TO"}
}
Above is the response you will receive if connection setup is successful.

Step 2: Redirect to auth_url

Redirect user to auth_url. Once redirected there's else nothing to do but wait.

Step 3: Listen for POST request at data_url

Once the user has selected the questions, we would send a HTTP POST to data_url with the request body containing the JSON question data.

Please respond with a status code of either 2xx to redirect user to success_url or anything other than 2xx (3xx, 4xx, 5xx) and we will redirect to cancel_url. You should ensure that your data_url enables you to securely identify whom the data belongs to.

Step 4: Receive user redirect at either success_url or cancel_url

We will redirect user back to your site based on the response status code from data_url. A 2xx status code will redirect to success_url and everything else will go to cancel_url. This completes the entire process.

GETMARKED User Connect

User Connect allows users from GETMARKED to Single Sign-On directly into a partner app. Partner apps would be featured prominently on our site. As our users are using GETMARKED Digitaliser to create digital assessments, this offers partner apps a available avenue to gain highly qualified users that are 100% in on using digital technologies.

We expect partner apps to offer a substantial free tier for users and also make available Item Bank Connect to them if you want to leverage this facility.

App registration

To start, please register your app using a developer account with us first. We would need the following information:
  • App Name
  • App Description
  • App Domain
  • App Login URL
App Name and App Description are user facing. App Domain will be the only domain we will interact with. App Login URL will be the endpoint where we will initate the SSO. This registration is subject to approval. We will reach out through email to arrange for a meeting. Once approved, you would be able to start using this facility.

Both Item Bank Connect and User Connect can share the same app registration.

Step 1: A HTTP GET request will be sent to App Login URL


https://PARTNER_APP_LOGIN_URL?email_address=...&id=...&secret=...
We will initiate the SSO with a GET request to App Login URL with secret, email_address and id as query parameters.

secret is provided to you after the app registration and is used to verify that they request came from us. id is a unique identifier of the user. email_address is the email address that users signed up with or provided to us from their LMS through an LTI integration. You should not use email_address to identify users as it is not reliable. While we verify the email address of everyone who signs up for a GETMARKED account, accounts created through an LTI integration from a LMS typically do not verify their users' email address. 

{
    "sso_url": "https://PARTNER_APP_SSO_URL",
}
We expect to receive a JSON response containing a sso_url to redirect our user to in successful SSO. If sso_url is not found, then the SSO will be considered as failed and we will handle it internally at GETMARKED.

Step 2: Redirect user to sso_url

we will redirect user to sso_url. This completed the entire process.