Kurtosys App Auth Service - Authentication

The Kurtosys App authentication service deals with the basic matter of authenticating against the system. If you are a Kurtosys client (someone using our system), it is likely you'll only need to use the login method, but from time to time you may have need to use the other methods which are documented here.

Login /auth/login

To perform any activity in the Kurtosys App a user token is required. This is retrieved by logging in via the login method. The method requires a userName, password and clientName. Tokens expire after a certain amount of time. This is configurable by client, but the default is 30 minutes. The exception to this is permanent tokens. Tokens are passed to the X-KSYS-TOKEN header of other web service calls. If the user has Two Factor Authentication (2FA) enabled, the response will be a temporary token that will start with 2fa- that must be upgraded using the auth/2fa/login endpoint.

We also support mTLS authentication that is configurable per Client or User.

Service call details

Body

{
    "userName": "jim.smith",
    "password": "secretpassword",
    "clientName": "ABC Capital Management"
}

or if passing X-KSYS-APP (see above)

{
    "userName": "jim.smith",
    "password": "secretpassword"
}

Response

A valid token will be in the format 00000000-0000-0000-0000-000000000000. A temporary token will be in the format 2fa- i.e. 2fa-00000000-0000-0000-0000-000000000000

Extend Login /auth/extendLogin

Will extend the expiry of an token setting the new expiry as described in Login. Only works with temporary tokens.

Response

A valid token will be in the format 00000000-0000-0000-0000-000000000000.

Available 2FA methods /auth/2fa

Lists the methods that have been enabled for 2FA.

Service call details

Response

[
    {
        "type": "PUSH"
    },
    {
        "type": "CALL",
        "phone": "+44*******327"
    },
    {
        "type": "TEXT",
        "phone": "+44*******327"
    }
]

Available 2FA methods /auth/2fa/login

Completes the login process for 2FA enabled users. This takes a 2FA temporary token that was returned in the /auth/login call.

Service call details

Request

{
    "type": "PUSH"
}

or

{
    "type": "TEXT"
}

or

{
    "type": "TEXT",
    "passcode": "123456"
}

Logout /auth/logout

Will destroy a valid token, effectively logging the user out of the system. Only works with temporary tokens.

Create Permanent Token /auth/createpermtoken

Permanent Tokens are used in tools projects - specifically for calls to the APIs which are embedded in web pages. Requires a userId. Can only be created by a Super Admin user. Permanent tokens can be only created for users with the ApiUser or CacheAdmin role.

Service Call Details

Body

{
    "userId": 8
}

List Permanent Tokens /auth/listpermtokens

Permanent Tokens are used in tools projects - specifically for calls to the APIs which are embedded in web pages. Lists all permanent tokens for a given user. Can only be called by a Super Admin user.

Service Call Details

Body

{
    "userId": 8
}

Example Response

Tokens are obscured.

[
    {
        "token": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx12"
    },
    {
        "token": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx34"
    },
    {
        "token": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx56"
    },
    {
        "token": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx78"
    }
]

Delete Permanent Token /auth/deletepermtoken

Permanent Tokens are used in tools projects - specifically for calls to the APIs which are embedded in web pages. Can only be deleted by a Super Admin user.

Service call details

Body

{
    "token": "xxxx"
}

Login /auth/requestStrategies

Retrieves a list of authentication strategies for an organization.

Service call details

Body

{
    "organization": "ABC Capital Management"
}

Response

[
    {
        "name": "ABCCapitalManagement",
        "type": "saml"
    }
]

Request Password Reset /auth/password-reset

If a password is forgotten, this is when the reset password functionality can help you out. An email will then be sent to the user's email address with further instructions on how to complete the password reset request.

Service call details

Body

{
    "userName": "jim.smith"
}

Validate Code /auth/validate-code

After receiving the email from the /auth/password-reset or /auth/registerNewUser, the passwordRequestId can be validated to check that it is still valid and is for the correct type of reset (password or registration or self-registration).

Service call details

Body

{
    "passwordRequestId": "XYZ123XYZ",
    "type": "password"
}

Response

{
    "imageRequired": true,
    "messageRequired": true
}

{
    "error": "code is invalid"
}

{
    "message": "ok"
}

Password Complexity /auth/password-requirements

Before passwords can be updated, there are certain configurable requirements that need to be met. The configuration can be retrieved by sending the passwordRequestId to the password-requirements endpoint.

Service call details

Body

{
    "passwordRequestId": "XYZ123XYZ"
}

Response

{
    "minLength": 13,
    "maxLength": 128,
    "minLetters": 1,
    "minNumbers": 1,
    "minPunctuation": 0,
    "requireUppercaseAndLowercase": false,
    "limitCharacterRepetition": false,
    "enforcePreviousPasswordCheck": false
}

Reset Password /auth/update-password

After receiving the password reset email from /auth/password-reset or after the user has been created, you can either click the link or use the passwordRequestId to complete the password reset. An email will then be sent to the user's email address confirming the password has been reset. If this is a registration type and the client has enabled assurance messages and/or images, these must be provided when setting the password. Please note that a user is not allowed to reuse old passwords.

Service call details

Body

{
    "passwordRequestId": "XYZ123XYZ",
    "password": "newPassword12345",
    "confirmPassword": "newPassword12345",
    "imageId": "212aa7e9-fadf-4cc3-a010-6950c2837a25",
    "message": "A message"
}

Assurance /auth/assurance

If assurances are enabled for a client, the response to this call will return the user's message and/or image. It can be called with or without a token. If a token is provided, the body is ignored, and the configured assurance message and assurance image are returned for the current logged in user. If a token is not provided, the username and client are used to determine the assurance message/image. A "consistently random" image/message is returned when either the user and/or client do not exist, or when the user doesn't have assurances configured. This means that if the same username is entered multiple times, it will return the same result.

Service call details

Body

{
    "username": "user12345",
    "clientName": "client1"
}

Response

{
    "assuranceImageEnabled": true,
    "assuranceMessageEnabled": true,
    "imageId": "cd4a0a9c-d117-468d-bf86-f0d6a2445cb6",
    "image": "/9j/4AAQSkZJRgABAQAAAQ....//Z",
    "message": "Windy City"
}

Get Assurance Image /auth/assurance/getImage

Gets the image with the provided id in IMAGE or JSON format. If a token is provided the passwordRequestId field is ignored.

Service call details

Body

{
    "passwordRequestId": "82989116-fb83-43b6-b305-c60bfd4dd5d6",
    "imageId": "212aa7e9-fadf-4cc3-a010-6950c2837a25",
    "format": "json"
}

Response

Binary Image.

or, if

{
    "format": "json"
}

{
    "image": "/9j/4AAQSkZJRgABAQAAAQ....//Z"
}

Get Assurance Images /auth/assurance/getImages

Returns a list of assurance images up to the number specified using the limit field (defaults to 10). If a token is provided, the passwordRequestId field is ignored.

Service call details

Body

{
    "passwordRequestId": "82989116-fb83-43b6-b305-c60bfd4dd5d6",
    "limit": 9
}

Response

{
    "images": [
        {
            "imageId": "212aa7e9-fadf-4cc3-a010-6950c2837a25",
            "image": "/9j/4AAQSkZJRgABAQAAAQ....//Z"
        }
    ]
}

Request Username /auth/username-request

This call will send out a username reminder email to the user associated with the email address provided. The list of usernames will be restricted to the application related to the applicationCode provided. This will return all organizations the user belongs to for this applicationCode.

Service call details

Body

{
    "email": "[email protected]"
}

Update Assurance Details /auth/assurance/update

Updates a user's assurance image and message.

Service call details

Body

{
    "imageId": "212aa7e9-fadf-4cc3-a010-6950c2837a25",
    "message": "Hello World!"
}

Upsert Users To Impersonate /auth/impersonation/upsert

Service call details

Body

{
    "username": "alexander.bell",
    "impersonationListType": "INCLUDE",
    "users": ["nikola.tesla", "isaac.newton", "stephen.hawking", "charles.darwin"]
}

List Users To Impersonate /auth/impersonation/list

Service call details

Body

{
    "username": "alexander.bell"
}

Response Body

{
    "impersonationListType": "INCLUDE",
    "users": ["nikola.tesla", "isaac.newton", "stephen.hawking", "charles.darwin"]
}

Impersonate a user /auth/impersonation/impersonate

Allows a user to impersonate another user. When impersonating another user, you have access to all their roles and permissions, and can perform any actions they are allowed to do, apart from impersonating another user.

The user who is impersonated will be notified by email of this activity.

Service Call Details

Body

{
    "username": "Alexander Bell"
}

Impersonate a user /auth/impersonation/stopimpersonating

Stops the current impersonation session and switches back to the original user's roles and access.

Service Call Details

Body

{}

Search for impersonation users /auth/impersonation/search

Can be used to search for users who can be impersonated by the current user.

Service Call Details

Body

{
    "userName": "Bell",
    "start": 0,
    "limit": 10
}

Example response

{
    "total": 2,
    "values": [
        {
            "userName": "Alexander Bell"
        },
        {
            "userName": "Alexandra Bell",
            "impersonating": true
        }
    ]
}

Search for impersonation sessions /auth/impersonation/sessions/search

Can be used to search for impersonation sessions by user and/or date range. If no filters are provided, all sessions for the client of the requestor will be returned.

Service Call Details

Body

{
    "impersonator": "Kevin Adkins",
    "userName": "Bell",
    "startDateRange": ["2017-01-01T00:00:00Z", "2017-12-31T23:59:59.999Z"],
    "limit": 10,
    "start": 0
}

Example response

{
    "total": 2,
    "values": [
        {
            "impersonator": "Kevin Adkins",
            "userName": "Alexander Bell",
            "startTimestamp": "2017-01-01T00:00:00Z",
            "stopTimestamp": "2017-01-01T00:15:00Z"
        },
        {
            "impersonator": "Kevin Adkins",
            "userName": "Liberty Bell",
            "startTimestamp": "2017-01-02T00:00:00Z",
            "stopTimestamp": "2017-01-02T00:15:00Z"
        }
    ]
}

Get Default Permanent Token /auth/getDefaultPermanentToken

Each client can have a default permanent token setup to allow for more efficient creation of Apps. This endpoint will retrieve that default token. A user can only fetch default tokens of other clients if they have the CREATE_PERMANENT_TOKEN permission. Otherwise they will only be able to get the default token from their own client instance.

Service call details

Body

{}

Example response

[
    {
        "userId": 4,
        "userName": "api.user",
        "token": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx12"
    }
]

Set Default Permanent Token /auth/setDefaultPermanentToken

Sets the default permanent token according to the client the token belongs to. The user must have the CREATE_PERMANENT_TOKEN permission.

Service call details

Body

{
    "token": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx12"
}

Example response

true