Connecting to the Surpass API v2

Requests to the Surpass API must be authenticated. This is akin to logging in with user credentials. However, the user specified in the request must also have the Surpass permissions required to authorise the action taken.

This article explains how to connect to the Surpass API v2 and which permissions are required to successfully call each API.

In this section

Authentication

If you are logged in to and are using the Surpass API v2 test console to send requests to the Surpass API, a token is sent with each request to the Surpass API to authenticate the request.

To authenticate requests sent to Surpass APIs from a different HTTP client, send basic authentication details in an authorization header. This is documented in the parameters tables of the reference documentation as follows:

Name	Parameter	Input	Description
authorization	header MANDATORY	`Basic {credentials}`	Basic authentication details must be passed to authorise the user’s request, where `{credentials}` is a Base64 encoded `username:password` string.

Name

Parameter

Input

Description

authorization

header

MANDATORY

Basic {credentials}

Basic authentication details must be passed to authorise the user’s request, where {credentials} is a Base64 encoded username:password string.

Connection to the Surpass API can also be authenticated using SAML if using Single Sign-On (SSO) to access Surpass. A SAML header parameter is passed in the request, with its value generated using the credentials specified in the SSO setup. For more information on SSO, read Single Sign-On.

TIP: We recommend creating a dedicated integration user that can be used when calling the Surpass API. This is a good idea even if you are only testing the API as it enables you to work in the Surpass UI and API simultaneously without being logged out of the UI after each request to the API.

NOTE: If the request does not contain valid authentication details, a 401 error is returned.

Authorisation

For requests sent to Surpass APIs to be authorised, the user sending the request must have the requisite Surpass permission(s). Each part of the system has a unique permission, which acts as a key.

Users can also be assigned roles at subject, centre, and site-level. If the user making the request only has subject or centre-level access, then whatever it is they are requesting needs to be in the relevant subject and/or centre. For more information on roles and permissions in Surpass, read About roles and permissions.

NOTE: If the user sending a request does not have the requisite permissions, a 403 error is returned.

Requisite permissions

Expand the following section for tables detailing which permission is needed to successfully call each Surpass API.

Item Authoring

API	Permission
BasicPage API	The requisite permissions for this API vary as follows: Item Authoring > Preview/View Content permissions for items at the corresponding status (GET). Item Authoring > Edit permissions for items at Draft status (POST). Item Authoring > Edit permissions for items at the corresponding status (PUT, DELETE).
Folder API	The requisite permissions for this API vary as follows: Item Authoring > Preview/View Content permissions (GET). Item Authoring > Edit permissions (POST, PUT).
Item API	The requisite permissions for this API vary as follows: Item Authoring > Preview/View Content permissions for items at the corresponding status (GET). Item Authoring > Edit permissions for items at Draft status (POST). Item Authoring > Edit permissions for items at the corresponding status (PUT, DELETE).
ItemList API	The requisite permissions for this API vary as follows: Item Lists for standard item lists. Share Items for subject master lists.
ItemSet API	The requisite permissions for this API vary as follows: Item Authoring > Preview/View Content permissions (GET). Item Authoring > Edit permissions (POST, PUT, DELETE).
ItemTagValue API	Item Authoring > Edit permissions for items at the corresponding status.
LanguageVariant API	The requisite permissions for this API vary as follows: Item Authoring > Preview/View Content permissions for item language variants at the corresponding status (GET). Item Authoring > Edit permissions for item language variants at Draft status (POST). Item Authoring > Edit permissions for item language variants at the corresponding status (PUT, DELETE).
Media API	The requisite permissions for this API vary as follows: Item Authoring > Preview/View Content permissions (GET). Item Authoring > Edit permissions (POST).
MediaGroup API	The requisite permissions for this API vary as follows: Item Authoring > Preview/View Content permissions (GET). Item Authoring > Edit permissions (POST, PUT).

Tasks

API	Permission
Task API	The requisite permissions for this API vary as follows: General Manager for General tasks. Review Manager for Review tasks. Review Assignee for updating Review task results. Authoring Manager for Authoring tasks. Standard Setting Manager for Standard Setting tasks. Standard Setting Assignee for updating Standard Setting task results.
TaskAttachment API	The requisite permissions for this API vary as follows: General Manager for General tasks. Review Manager for Review tasks. Authoring Manager for Authoring tasks. Standard Setting Manager for Standard Setting tasks.

API

Permission

Task API

The requisite permissions for this API vary as follows:

General Manager for General tasks.
Review Manager for Review tasks.
Review Assignee for updating Review task results.
Authoring Manager for Authoring tasks.
Standard Setting Manager for Standard Setting tasks.
Standard Setting Assignee for updating Standard Setting task results.

TaskAttachment API

The requisite permissions for this API vary as follows:

General Manager for General tasks.
Review Manager for Review tasks.
Authoring Manager for Authoring tasks.
Standard Setting Manager for Standard Setting tasks.

Test Creation

API	Permission
Test API	Create Tests
TestForm API	Create Tests
TestProfile API	Manage Test Profiles

Test Administration

API	Permission
SummaryResult API	Results
Result API	Results
TestSchedule API	Schedule Test > Edit
TestSession API	The requisite permissions for this API vary as follows: Invigilate Test > Read-only permissions (GET). Invigilate Test > Edit permissions (GET`/{id}`). Void Test (PUT). Upload Responses for assigning marks or Multiple Choice responses.

Reporting

API	Permission
AnalyticsResult API	Results and View Reports
AnalyticsScaleScoreMapping API	View Reports
CustomReport API	Manage Custom Report Template
CustomReportGeneration API	Generate Custom Report
HistoricalResult API	View Reports
RescoringRule API	Rescore Candidate Script
Report API	View Reports
ScaleScoreMapping API	View Reports

Setup

API	Permission
Candidate API	Manage Candidates
Centre API	Manage Centres
CentreSubjectAssociation API	Manage Centres and Manage Subjects
Country API	N/A
County API	N/A
Permission API	Manage Users
Subject API	Manage Subjects
Tag Category API	Manage Subjects
TagCollectionGroup API	Manage Subjects
TagGroup API	Manage Subjects
TagValue API	Manage Subjects
User API	Manage Users
UserPermission API	Manage Users
WorkflowStatus API	N/A

Misc.

API	Permission
Token API	Create Keycode Token NOTE: This permission is not available in the Surpass UI. If you would like more information about this permission, contact your Surpass Customer Success Manager.