Permission API
In Surpass, a user’s ability to view and interact with different parts of the system depends on their “permissions”. Each part of the system has a unique permission, which acts as a key. Only users with the relevant permission can access a given part of the system. If a user does not have permissions for an area of the system, they will not see it.
Individual permissions can be combined into a profile called a “role”, which can then be given to a user. A role gives a user all of the included permissions. Each role in Surpass has a unique identifier. Read Creating a new role for information on how to create a custom role.
The Permission API resource is used to list permissions (roles).
This article explains what calls can be made to the Surpass API using the Permission resource.
Import this API into your Postman Workspace
In This Article
Listing permissions
Send a request to the endpoint to retrieve a list of permissions (roles). Refer to the available parameters to influence the response. No request body is required.
Parameters
Parameters are passed with the endpoint to influence the response. Header parameters are included in the request header. Path parameters are extensions of the endpoint, and query parameters follow ?$ after any path parameters.
|
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. |
|
accept |
header OPTIONAL |
application/json or application/xml |
Determines data format of the response, which can be either JSON or XML. |
Sample response
If successful, the HTTP status code will be 200 and the response body will contain the information in either JSON or XML format as requested.
{
"count": 35,
"top": null,
"skip": null,
"pageCount": null,
"nextPageLink": null,
"prevPageLink": null,
"response": [
{
"id": 2,
"name": "Site Administrator"
},
{
"id": 3,
"name": "Centre Administrator"
},
{
"id": 4,
"name": "Create Subjects"
},
{
"id": 5,
"name": "Subject Owner"
},
{
"id": 6,
"name": "Subject User"
},
{
"id": 7,
"name": "Item Writer"
},
{
"id": 8,
"name": "Create Tests"
},
{
"id": 9,
"name": "Schedule"
},
{
"id": 10,
"name": "Invigilate"
},
{
"id": 11,
"name": "Mark"
},
{
"id": 12,
"name": "Moderate"
},
{
"id": 13,
"name": "View Results"
},
{
"id": 14,
"name": "Re-mark"
},
{
"id": 15,
"name": "View Reports"
},
{
"id": 16,
"name": "Audit"
},
{
"id": 17,
"name": "Item Reviewer"
},
{
"id": 18,
"name": "Item Publisher"
},
{
"id": 20,
"name": "Manage Centres"
},
{
"id": 21,
"name": "Manage Subjects"
},
{
"id": 22,
"name": "Manage Users"
},
{
"id": 23,
"name": "Manage Candidates"
},
{
"id": 24,
"name": "Upload Paper Tests"
},
{
"id": 25,
"name": "Candidate Review"
},
{
"id": 27,
"name": "Bulk Schedule"
},
{
"id": 28,
"name": "Site Settings"
},
{
"id": 29,
"name": "Manage Test Profiles"
},
{
"id": 30,
"name": "Manage Regional Settings"
},
{
"id": 31,
"name": "Rescore Candidate Script"
},
{
"id": 33,
"name": "Manage Profile"
},
{
"id": 34,
"name": "Homepage Editor"
},
{
"id": 59,
"name": "Access External Application"
},
{
"id": 69,
"name": "Task Administrator"
},
{
"id": 70,
"name": "Manage Custom Reports"
},
{
"id": 71,
"name": "Generate Custom Reports"
},
{
"id": 72,
"name": "Admin Console"
},
{
"id": 73,
"name": "SecureClient Administrator"
},
{
"id": 74,
"name": "Manage LOFT/Adaptive and Item Pools"
}
],
"errors": null,
"serverTimeZone": "GMT Standard Time"
}Response schema
The response schema contains a description of every property that can be returned for this endpoint.
count integer
Details how many roles there are in total.
top integer
Details number of roles returned in the response. This property is always returned as null.
skip integer
Details how many roles were skipped to display those in the response. This property is always returned as null.
pageCount integer
Details how many pages of roles there are. This property is always returned as null.
nextPageLink string
The endpoint to call the next page of roles. This property is always returned as null.
prevPageLink string
The endpoint to call the previous page of roles. This property is always returned as null.
response array
Contains the rest of the response.
id integer
The role’s unique identifier.
name string
The role’s name.
errors string
Information about any errors that occurred during the request.
serverTimeZone enumeration
The timezone of the server sending the response.
Error Codes
Refer to the following table for information on error codes that may be encountered when using this resource.
|
Name |
Code |
Description |
|---|---|---|
|
InternalServer |
1 |
Internal server error. |
|
Unauthorized |
3 |
The request has been sent by an unauthorised user. |
|
IncorrectFieldFormat |
4 |
A field in the request has not been completed in the correct format. |
|
InaccessibleOperation |
5 |
The request has been sent by a user with invalid permissions. |
|
InaccessibleData |
6 |
The request has been sent by a user with invalid permissions. |
Further reading
Read the following articles to learn more about similar APIs, how to get started with the Surpass API v2, and how to get the best out of this reference documentation: