The Token API resource is used to generate a token that can be used to access candidate responses from either a Mark or Audit perspective from an external system. For more information on the Mark and Audit screens in Surpass, read About the Mark (Standard) screen and About the Audit screen.
The Token API resource is used to generate bearer tokens.
This article explains what calls can be made to the Surpass API using the Token resource.
Import this API into your Postman Workspace
In This Article
Generating a token
post/api/v2/Token
Send a request to the endpoint to generate a bearer token. This can be used to gain access to the Mark or Audit screens.
IMPORTANT: Although bearer tokens can be passed in the querystring of a URL, it is best practice to send them in an authorization header.
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.
content-type
header
MANDATORY
application/json or application/xml
Determines data format of the request, which can be either JSON or XML.
content-length
header
MANDATORY
{number}
Determines the number of characters passed in the body of the request, where {number} is a numerical figure. This is usually automatically calculated when the request is sent.
accept
header
OPTIONAL
application/json or application/xml
Determines data format of the response, which can be either JSON or XML.
Sample request
The following request contains the minimum required request body to generate a token.
{
"Keycode": "Y6NWPC7K"
}
EXAMPLE: In this sample request, a Mark token is generated for keycode Y6NWPC7K.
Request body schema
The request body schema contains a description of every property that can be passed with this endpoint.
Keycodestringmandatory
The candidate’s unique keycode. This restricts the access granted by the token to this keycode.
NOTE: The test session for the specified keycode must be in Finished state.
UserNamestringmandatory
The user’s username. This restricts the access granted by the token to this user.
IMPORTANT: If Keycode is also passed in the request, UserName is ignored and a keycode-level token is generated.
TokenTypeenumerationoptional
Determines the token type. This can be either Mark (grants access to the Mark screen) or Audit (grants access to the Audit screen). Defaults to Mark if omitted.
Sample response
If successful, the HTTP status code will be 200 and the response body will contain the generated token.
EXAMPLE: This response is for a user-level token. The token is in the reference property.
Response body schema
The response body schema contains a description of every property that is returned by this endpoint.
idinteger
The token’s unique identifier. This property always returns as null.
referencestring
The token.
hrefstring
The endpoint used to generate the token. This property always returns as null.
errorsstring
Information about any errors that occurred during the request.
serverTimeZoneenumeration
The timezone of the server sending the response.
keycodestring
The candidate’s unique keycode, used to enter their test. Returns null if the token requested is user-level.
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.
MissingBody
7
There is an issue with the request body.
InvalidReference
11
The unique reference code used in the request is invalid.
InvalidInputParameters
15
There is an issue with the path or query parameters.
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:
