Inspera Assessment API

 

General information

The Inspera Assessment API is a set of open REST APIs allowing external systems to access a subset of Inspera Assessment functionality using Inspera Assessment user privileges. The functionality provided includes creating and updating Test Events, assigning and removing Learners and Contributors from Test Events, exporting results and responses after marking/grading, as well as user management.

We develop and update and add new APIs continuously. All changes and additions to existing APIs, as well as new developed APIs and API roadmap plans are announced through Inspera's release notes. Please see our product site to learn about how to subscribe to release notes. 

Design principles

The Inspera APIs are designed based on the following core principles:

  • Inspera APIs provide endpoints for pushing and pulling data
  • Inspera Webhooks provide outgoing notifications about events in Inspera services
  • Both the APIs and the Webhooks are designed to be generally reusable - no tight coupling with external systems
    • Integration layers typically sit between the Inspera API/Webhooks and external services providing any conversion required to ensure system interoperability
  • OAuth is used for authentication
  • Authorisation is handled through the same core permission model as is used across the rest of the Inspera Assessment service

Inspera APIs in customer landscape

Illustration of how the Inspera APIs fit into the customer system landscape for Higher Ed (click on the image to open in full size in a new tab).

API1.png

Getting started

First steps

To get started, you will need a user in Inspera Assessment, with Administrator privileges. From the user profile interface, you will then be able to access the API key details for either yourself or other Inspera users in your organization. These authorization details will include an API key (authorization code). In addition to this code, client id is needed to be able to send API call to obtain authentication token. This will be explained later in this document.

The API key will be accessible only once and if a user loses or forgets their API key, any administrator for your organization will be able to revoke that user's access and generate a new code for them.

Information:

Generating API keys can only be done by users that have the User Admin role.

Calls made with a given API key will follow the same privileges as the linked user account has. The same goes for Webhook notifications. We strongly recommend creating dedicated Integration users on your Inspera Assessment tenant, and use API keys from these users for integration API calls. This is to make the integration independent of personal user accounts.

Where is the API key located in Inspera Assessment user interface?

Open "User administration" from Inspera Assessment main page and search for user you want to generate key for. The following will appear on the screen:

2023-10-18_16h11_44.png

After clicking on Generate API authorization code:

2023-10-18_16h13_20.png

After exiting the user, the API key will never be shown again. A new key can only be regenerated after revoking access:

2023-10-18_16h14_00.png

 

How to obtain client_ID?

"client_ID" is a parameter needed for the correct access token to be generated. This value is, in most cases, host-part of the domain of your Inspera Assessment url. For instance, if your Inspera URL is https://test.inspera.com/ , clientID will be "test". However, this may not be the case if you have a custom URL, in which case you will find the clientID in user administration (see above).

Once a user has their authorization code and have obtained client id, they will be able to start using the APIs.

Making API calls

The APIs listed below are available via HTTPS requests (see the specific API documentation for details).

To obtain access token, a call should be made in the following format:

curl -d "" -H "code:<your user API authorization code>" "https://<your inspera domain>/api/authenticate/token/ ?grant_type=authorization_code&client_id=<your client_id>"


All the APIs assume a base url in the following format:

https://<your inspera domain>/api

In this table you will find key values for API authentication:

  Value
URL /api/authenticate/token/
Method POST

URL Parameters:

*required

 
grant_type* authorization_code
client_id* (string), please see above for more details on how to obtain this information)

HEADER Parameters:

*required

 
code* (string)

Data Parameters:

(required for POST)

 
Content-Type application/x-www-form-urlencoded
Responses:  
200

Success

Returns: 

{
  "access_token": string,   
  "expires_in": integer
}
400

Error: Bad request

Returns:

{
  "error": [OAuth2Exception]
}
401

Error: Unauthorized

Returns:

{
  "error": "invalid_grant"
}
409

Error: Conflict

Returns:

{
  "error": "Multiple tokens for user",
  "description": "Please contact inspera support"
}
500

Error: Internal server error

Returns:

{
  "error": "Internal error authenticating user",
  "description": "Please contact inspera support"
}
501 Error: not implemented

 

Sample scenario using command line tools to authenticate and get test results

Below we go through using the API from the command line, assuming the curl tool is installed. Since all messages are in JSON, jq is also very handy and will give you color coding and easy data extraction when working from the command line or in shell scripts.

This scenario is not covering all details - please see the actual API documentation for the specifics on the formats of the requests and responses.

Sample

Required data used in this sample

Field Value
User authorization code (from Inspera user administration) 123456-7890-abcd-efgh
Inspera domain demo.inspera.no
client_id demo

 

Step 1: authenticate and obtain access token

curl -d "" -H "code:123456-7890-abcd-efgh" "https://demo.inspera.no/api/authenticate/token/ ?grant_type=authorization_code&client_id=demo" # (the space before ? is to prevent confluence to escape the remainder of the url - don't include it when you make the call yourself)

Note:

The option -d "" makes curl send a POST request with empty body and content type application/x-www-form-urlencoded, which the authentication API requires.

This will, if successful, return a JSON containing an access bearer token (in this example: "xyz-abcd-efg" and a lifetime in seconds)

The response will look like:

{
    "access_token": "xyz-abcd-efg",
    "expires_in": 3600
}

 

Step 2: Send API call

Example 1:

In this example, API call is made to get test metadata for test with testID=12312312 using this API https://ia.inspera.no/apidoc/#/test/getTestMetadata

curl -H "Authorization: bearer xyz-abcd-efg" https://demo.inspera.no/api/v1/test/12312312

Or, if we wanted to keep the access token from the command line, we can use jq to just store it as an environment variable and reuse it:

auth_response=$(curl -d "" -H "code:123456-7890-abcd-efgh" "https://demo.inspera.no/api/authenticate/token/ ?grant_type=authorization_code&client_id=demo")   #   (the space before ? is to prevent confluence to escape the remainder of the url - don't include it when you make the call)
token=$( jq -r  '.access_token' <><><"${auth_response}" 12312312="12312312" )=")" 
curl="curl" -h="-H" authorization:="Authorization:" bearer="bearer" ${token}="${token}" https:="https:" demo.inspera.no="demo.inspera.no" api="api" v1="v1" test="test"></"${auth_response}"></></>

 

Example 2:

In this example, API call is made to export results for a learner on a given test using this API: https://ia.inspera.no/apidoc/#/candidates/getCandidateResult

test_id= 12312312

user_id=987654

curl -H "Authorization: bearer xyz-abcd-efg" https://demo.inspera.no/api/v1/candidates/result/12312312/987654

Since this API can fetch a significant amount of data, it will, instead of immediate results, return a callback url:

https://demo.inspera.no/api/v1/candidates/results/12312312/987654

Performing a get for this will return either the status of the export, or, once it's done (usually under 5s), a short-lived url for downloading the JSON of the export.

curl -H "Authorization: bearer xyz-abcd-efg" https://demo.inspera.no/api/v1/candidates/results/12312312/987654

Finally, the admin user can take the provided url and download and use the export of the test results.

 

Artikler i denne seksjonen

Var denne artikkelen nyttig?
0 av 0 syntes dette var nyttig