Settings OAPI
You can update your Surpass instance’s public key (for use with JWT authentication) and enable or disable basic authentication using the Settings OAPI. For more information on JWT (JSON web tokens) authentication, read Connecting to the Surpass OAPI.
Equally, if the Settings OAPI contains an incorrect public key, although a lost public key can be derived from its private key and re-added to your Surpass instance, with basic authentication disabled you would not be able to authenticate a request to do this.
This article explains what calls can be made to the Surpass OAPI using the Settings resource.
Import this API into your Postman Workspace
In This Article
Retrieving authentication settings
Send a request to retrieve the basic authentication status and active public key for your Surpass instance.
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 OPTIONAL |
Basic {credentials} |
Basic authentication details must be passed to authorise the user’s request, where {credentials} is a Base64 encoded username:password string. |
|
authorization |
header OPTIONAL |
Bearer {token} |
A bearer token must be passed to authorise the user’s request, where {token} is a JWT (JSON web token). |
|
accept |
header OPTIONAL |
application/json |
Determines data format of the response (JSON). |
Sample response
If successful, the HTTP status code will be 200 and the response body will contain basic authentication status and the public API key as requested.
{
"publicAPIKey": "string",
"allowBasicAuth": true
}Response schema
The response schema contains a description of every property that can be returned for this endpoint.
publicAPIKey string
The active public API key.
allowBasicAuth Boolean
Determines whether basic authentication is enabled (true) or not (false)..
Updating authentication settings
Send a request to the endpoint to update whether basic authentication is enabled and/or the active public key for your Surpass instance.
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 OPTIONAL |
Basic {credentials} |
Basic authentication details must be passed to authorise the user’s request, where {credentials} is a Base64 encoded username:password string. |
|
authorization |
header OPTIONAL |
Bearer {token} |
A bearer token must be passed to authorise the user’s request, where {token} is a JWT (JSON web token). |
|
content-type |
header MANDATORY |
application/json |
Determines data format of the request (JSON). |
|
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 |
Determines data format of the response (JSON). |
Sample request
The following request contains the minimum required request body to update the active public key or enable (or keep enabled) basic authentication.
{
"publicAPIKey": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAr4BUvgV91X1GKibQqyfejwj8uJw6cYOtEXbDjOZm0/A7Z6IY+Pxk4rrWy23Hqn2FQTlmkUtNSEAvndvnOA5sgVE9c41qwgw1AQHdZeL/DVb3g+j1oxIr8Z4WUbpsrD8YmaW8uIXt2WmcA0ZMNxzZ50A9aDlVr1Z9IDFx+qKZ11654o4ASgah9p5SQ2WHbWDegcn25geYDoDUVRERfjYiiAQWQ2+GlUTpU5CC3JJms64joWOU6k1REOMwb5mDmcTViv+svzWH3gwZUUQMg9E1RRlAVzJuoqEGhb4KpS2/58L0gA9rA4j9fyWJNpBFd1PjmsH/iMS7MdakeUA8dvKYaQIDAQAB",
"allowBasicAuth": true
}Request body schema
The request body schema contains a description of every property that can be passed with this endpoint.
publicAPIKey string
The active public API key.
allowBasicAuth Boolean
Determines whether basic authentication is enabled (true) or not (false).
Sample response
If successful, the HTTP status code will be 200 and the response body will contain the updated basic authentication status.
{
"publicAPIKey": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAr4BUvgV91X1GKibQqyfejwj8uJw6cYOtEXbDjOZm0/A7Z6IY+Pxk4rrWy23Hqn2FQTlmkUtNSEAvndvnOA5sgVE9c41qwgw1AQHdZeL/DVb3g+j1oxIr8Z4WUbpsrD8YmaW8uIXt2WmcA0ZMNxzZ50A9aDlVr1Z9IDFx+qKZ11654o4ASgah9p5SQ2WHbWDegcn25geYDoDUVRERfjYiiAQWQ2+GlUTpU5CC3JJms64joWOU6k1REOMwb5mDmcTViv+svzWH3gwZUUQMg9E1RRlAVzJuoqEGhb4KpS2/58L0gA9rA4j9fyWJNpBFd1PjmsH/iMS7MdakeUA8dvKYaQIDAQAB",
"allowBasicAuth": true
}Error Codes
Refer to the following table for information on error codes that may be encountered when using this resource.
|
Code |
Description |
|---|---|
|
222 |
publicAPIKey has invalid length for a Base64 encoded string.
|
|
401 |
The request has been sent by an unauthorised user. |
|
403 |
Resource cannot be accessed. |
Further reading
Read the following article to learn how to get started with the Surpass OAPI: