Connecting to the Surpass OAPI

Requests to the Surpass OAPIs must be authenticated using either user credentials or a bearer token. 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 OAPIs and which permissions are required to successfully call each API.

In this section

Authentication

There are two ways to authenticate and establish communication with the Surpass Platform:

Basic authentication – a quick way to establish connection with the server, akin to logging in with user credentials.
JWT authentication – authentication that offers a higher level of security by not putting user credentials at risk of exposure.

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

Basic authentication

If you are using the Surpass OAPI Swagger console to send requests to the Surpass OAPI, select Authorize to open the Available authorizations dialog.

Enter your credentials in the Username and Password fields and then select Authorize. A token is generated from your credentials and sent with each request to the Surpass OAPI in order to authenticate the requests.

To authenticate requests sent to Surpass OAPIs 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 OAPI 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 OAPI using basic authentication. This is a good idea even if you are only testing the OAPI as it enables you to work in the Surpass UI and OAPI simultaneously without being logged out of the UI after each request to the OAPI.

JWT authentication

JWT (JSON web token) authentication securely transfers information between client and server as a JSON object. Tokens are generated from a public and private key pair and used to identify the authenticated user without having to pass user credentials with each API request.

To authenticate requests sent to Surpass OAPIs using a JWT, follow these steps:

1. Generate a public and private key pair

Generate a 2048-bit public and private key pair using an RSA key generator. Public keys are used on the client-side to validate each request, and the private key is stored on the server to sign (and authenticate) each token.

IMPORTANT: Private keys must be kept secret, safely stored, and accessible to you, otherwise you risk unwanted access to your Surpass instance or losing access to it altogether.

2. Store private key on your server

Store your generated private key on your server, such as in the config file within the application from which you are generating tokens.

If using the Surpass JWT application for testing token authentication (contact support@surpass.com if you need this application), add your private key to the appSettings object in the Surpass.OAPI.JwtTokenGenerator.exe config file. You must also add your Surpass instance username to the UserName key-value pair, a token expiry value (in minutes) to Expires, and your Surpass instance URL to Issuer.

3. Add public key to your Surpass instance

Use the Settings OAPI to add the private key’s corresponding public key to your instance.

4. Generate a token

NOTE: Tokens expire, but there is no limit to how many tokens can be generated.

Generate your JWT. It is best practice to write something into your application that is calling the Surpass OAPI, to generate your tokens.

If using the Surpass JWT application, launch it. The application uses your configured private key to generate a JWT. Copy the token’s string (not including the Bearer prefix).

Header

{
    "alg": "HS256",
    "typ": "JWT"
}

Field	Description
`alg`	The algorithm used to sign the token.
`typ`	The type of token, which is `JWT`.

Payload

{
    "iss": "https://{your Surpass instance}.surpass.com/",
    "sub": "User 1",
    "jti": "d80b41dc-956b-40cf-9960-c82851be578d",
    "exp": 5,
    "aud": "api"
}

Field	Description
`iss`	The URL or server that has issued the token to make API calls.
`sub`	The user who made the request.
`jti`	The token’s unique identifier.
`exp`	The time period after which the token expires.
`aud`	The token’s audience (consumer).

Signature

NOTE: This is the secret key that is only known to the sender.

HMACSHA256(
   base64UrlEncode(header) + "." +
   base64UrlEncode(payload),
)

5. Use token to authenticate requests

If using the Surpass OAPI Swagger console, enter your JWT in the Value field of the Available authorizations dialog, and then select Authorize.

To authenticate requests sent to Surpass OAPIs from a different HTTP client, send your bearer token in an authorization header. This is documented in the parameters tables of the reference documentation as follows:

Name	Parameter	Input	Description
authorization	header MANDATORY	`Bearer {token}`	A bearer token must be passed to authorise the user’s request, where `{token}` is a JWT (JSON web token).

Name

Parameter

Input

Description

authorization

header

MANDATORY

Bearer {token}

A bearer token must be passed to authorise the user’s request, where {token} is a JWT (JSON web token).

WARNING: Token authentication can be enforced as the only method of authentication available for your Surpass instance by disabling basic authentication using the Settings OAPI. However, it is imperative your private key is safely stored and accessible to you (and the Settings OAPI is configured with its paired public key) so that a signed token can be generated, otherwise no user will be able to access your Surpass instance.

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.

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 OAPI.

Item Authoring

OAPI	Permission
Item OAPI	The requisite permissions for this OAPI 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).
ItemMetadata OAPI	Item Authoring > Edit permissions for items at the corresponding status.
ItemSet OAPI	Item Authoring > Edit permissions.

OAPI

Permission

Item OAPI

The requisite permissions for this OAPI 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).

ItemMetadata OAPI

Item Authoring > Edit permissions for items at the corresponding status.

ItemSet OAPI

Item Authoring > Edit permissions.

Reporting

OAPI	Permission
AnalyticsResult OAPI	Results and View Reports

Setup

OAPI	Permission
TagCollection OAPI	Manage Subjects
TagCollectionGroup OAPI	Manage Subjects
TagGroup OAPI	Manage Subjects
TagValue OAPI	Manage Subjects
TagValueItem OAPI	Manage Subjects

Misc.

OAPI	Permission
Settings OAPI	N/A