Developer Guide

Contents

API

We provide a RESTful API service to integrate OASIS within your own application quick and simple.

Header Parameters

All API requests require header parameters to ensure we correctly identify the request is for the OASIS account that is attempting to perform the request

 

X-OASIS-EPOCH

This is the epoch time of the request, the time in seconds since 1 Jan 1970, the time should be the current UTC time to ensure that that no matter the timezone we can still process the request, the time ensures that the request will expire in a short time to prevent man in the middle attacks.

X-OASIS-APPID

This is the application ID of the application you setup in the OASIS administration console.

X-OASIS-REQSECRET

This is a HMACSHA256 of the following string

{X-OASIS-APPID}:{X-OASIS-EPOC}:{Application key}:{request content}

 The application key is the key for the APP ID created in the OASIS administration console.

The request content will vary depending on the type of request.

 The key for the HMACSHA256 should be your API key available from your profile section of the OASIS administration console.

Standard API Response Parameters

All API request will respond with the following parameters:

RandomToken

A random token generated server side which is used as a part of signing the response.

SignedResponse

A hashed and encoded signature of the response to be verified Client side to ensure the request is from the expected API and more importantly the OASIS service

 

This is a HMACSHA256 of the following string

{SignedResponse}:{RandomToken}:{Data1 see individual API response}:{Data 2 see individual API response} 

SignedTime

The epoch time in seconds UTC time.

This time should be checked to ensure that the response is within an acceptable time span

Example

{SignedTime} < {Current epoch utc time in seconds} – (5 * 60)

RequestAuthorisationState API

Check is a user is required to provide the time based one-time passcode or if the user is already registered in the OASIS directory

Resource URL

POST https://oasis.oliveinnovations.com/api/ApplicationAPI/RequestAuthenticationState

Request Parameters

String

Username

Username present in the OASIS user directory or if the request is to check if the user is registered the user name you wish to check

VerificationTypeEnum

VerificationType

See verification type enum codes.

String

DirectoryName

(Optional)  If you have multiple applications which share the same OASIS integration you can specify a directory name for each integration. You must specify the same directory name for all requests.

Example Check Login Request

{

              Username: “a user”,

              VerificationType: “LOGIN”,

              DirectoryName: null

}

Response Parameters

 

UserAuthenticationStateEnum                        

State

See user authentication state enum codes.

Long

UserID

The userID code within the OASIS user directory, this can be used later to verify the user one-time passcode or to use other API methods to manage users.

String

UserQRCode

When creating new users it is possible to register users via email or if you prefer to handle registration completely in your application. This will be returned only when the request parameter VerificationType is REGISTRATION.

The QR code

NOTE: When verifying the SignedResponse {Data 1} = UserID and {Data 2} = State, see Standard API Response Parameters for more information

Example Check Authentication Response

{

              RandomToken: “xxxxxxxx”,

              SignedResponse: “xxxxxxx”,

              SignedTime: 12334,

              State: “xxxxx”,

              UserID: 1,

              UserQRCode: “xxxxx”

}

RegisterUser API

Register a user in the OASIS platform directory

Resource URL

POST https://oasis.oliveinnovations.com/api/ApplicationAPI/RegisterUser

Request Parameters

String

Username

The username to create

String

Fullname

Full name of the user

String

Email

Email address of the user

Bool

SendEnrollmentEmail

If you do not wish to handle the completion of the user registration in your own application you can pass true to have a enrolment email sent from the OASIS platform.

Array<int>

UserGroups

An array of user groups the user is a member of, this group ID’s can be found in the OASIS administration console.

String

DirectoryName

(Optional) If you have multiple applications which share the same OASIS integration you can specify a directory name for each integration. You must specify the same directory name for all requests.

NOTE: Specifying a directory name will cause responses with QR codes to replace the issue name registered with the directory name.

 Example Check Login Request

{

              Username: “a user”,

              Fullname: “Your Users Name”,

              Email: someaddress@yourdomain.com,

              SendEnrollmentEmail: “true”

              UserGroups: { 1, 2}

}

Response Parameters

Long

UserID

The userID code within the OASIS user directory.

String

UserQRCode

If you choose to handle the completion of the enrolment within you own application, you will returned an encoded QR code to display in an image html element.

Example User Registration Response

{

              UserID: 1,

              UserQRCode: “xxxxx”

}

DeleteUser API

Delete a user in the OASIS platform directory

Resource URL

DELETE https://oasis.oliveinnovations.com/api/ApplicationAPI/DeleteUser?username=

Request Parameters

String

Username

The username to delete

NOTE: If you are using optional directory name you must prefix the name with the directory i.e. {directory name}\{username}

VerifyUserOTP API

Register a user in the OASIS platform directory

Resource URL

POST https://oasis.oliveinnovations.com/api/ApplicationAPI/VerifyUserOTP

Request Parameters

long      

UserID

The userID returned from the RequestAuthenticationState API call, this is optional if Username is specified

String

Username

Username to verify, this is optional if UserID is specified

String

OTPCode

The user entered one-time passcode

VerificationTypeEnum

VerificationType

See verification type enum codes.

String

DirectoryName

(OPTIONAL) If you have multiple applications which share the same OASIS integration you can specify a directory name for each integration. You must specify the same directory name for all requests.

Example VerifyOTP Request

{

              UserID: 1

              Username: “some username”,

              OTPCode: “123456”

              VerificationType: 1

}

Response Parameters

UserAuthenticationStateEnum

State

See user authentication state enum codes.

String

UserToken

A unique token for a user.

String

Data

(OPTIONAL) If the VerificationType is REGISTRATION this will contain the base64 encoded QR image.

NOTE: When verifying the SignedResponse {Data 1} = UserID or Username depending on what was sent in the request and {Data 2} = State, see Standard API Response Parameters for more information

Example VerifyOTP Response

{

              RandomToken: “xxxxxxxx”,

              SignedResponse: “xxxxxxx”,

              SignedTime: 12334,

              State: 7,

              UserToken: null,

              Data: null,

}

Verification Type Enum Codes

0

LOGIN

To be used to check if the user is to provide one-time passcode. You would call this after a user enters there normal credentials to check to see if the additional one-time passcode should be entered, if they should then prompt them to enter it before calling the VerifyOTP API.

1

REGISTRATION

Check status of the user registration, you would use this if you are handling the registration of users for the OASIS service.

User Authentication State Enum Codes

0

NOTREGISTERED

User is not registered

1

DISABLED

User is disabled

2

LOCKED

User is locked for the configured duration due to too many consecutive failed verification attempts

3

NOGROUPMEMBERSHIP

User does not belong to any groups

4

NOTALLOWEDTOBYPASS

User is set to bypass authentication in the OASIS platform but the application does not allow authentication of users set to bypass.

5

SKIPAUTHENTICATION

Skip additional authentication of the user, one-time passcode is not required

6

AUTHENTICATE

User must authenticate by providing a one-time passcode

7

INVALID

Invalid one-time passcode entered.

8

VALID

Valid one-time passcode entered.

9

PENDINGENROLLMENT

User is pending enrolment.

10

MAXUSERSREACHED

You are on a free plan and the maximum number of allowed authentications has been reached for the current month