Fundpress Auth Service - Authentication

The fundpress 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, so they are documented here.

Login /auth/login

To perform any activity in fundpress 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 certian amount of time. This is configuarble by client, but the defualt 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.

Service call details.

Parameter Value
End Point https://api.fundpress.io/auth/login
Headers None or X-KSYS-APP (This is the applicationCode GUID)
Content Type application/json
HTTP Method POST
Return Type Text
Return Data A valid fundpress token for use in X-KSYS-TOKEN headers or a 2FA temporary token if 2FA is enabled for the user
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-The token will be in the format 2fa-00000000-0000-0000-0000-000000000000

Available 2FA methods /auth/2fa

Lists the methods that have been enabled for 2FA

Service call details.

Parameter Value
End Point https://api.fundpress.io/auth/2fa
Headers X-KSYS-2FATOKEN or 2fatoken cookie
Content Type application/json
HTTP Method GET
Return Type JSON
Return Data A list of enabled 2FA methods
Response
[
    {
        type: "PUSH",
    },
    {
        type: "CALL",
        phone: "+44*******327",
    },
    {
        type: "TEXT",
        phone: "+44*******327",
    },
];
JSON Key Description
type CALL, PUSH or TEXT
phone The users phone number (partially obfuscated)

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.

Parameter Value
End Point https://api.fundpress.io/auth/2fa/login
Headers X-KSYS-2FATOKEN or 2fatoken cookie
Content Type application/json
HTTP Method POST
Return Type TEXT
Return Data A valid fundpress token for use in X-KSYS-TOKEN headers
Request
{
    "type": "PUSH"
}

or

{
    "type": "TEXT"
}

or

{
    "type": "TEXT",
    "passcode": "123456"
}
JSON Key Required Description
type TRUE One of PUSH, CALL or TEXT
passcode FALSE The code that was sent to the user's device

Logout /auth/logout

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

Parameter Value
End Point https://api.fundpress.io/auth/logout
Headers X-KSYS-TOKEN
Content Type application/json
HTTP Method POST
Return Type Status Code Only
Return Data none

Create Permanent Token /auth/createpermtoken

Permanent Tokens are used in tools projects - specificaly 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 created on users with only the ApiUser or CacheAdmin role.

Service Call Details

Parameter Value
End Point https://api.fundpress.io/auth/createpermtoken
Headers None
Content Type application/json
HTTP Method POST
Return Type Text
Return Data A valid fundpress token for use in X-KSYS-TOKEN headers
Body
{
    "userId": 8
}
JSON Key Required Description
userId TRUE The id of the user to whom the token is to be grant

List Permanent Tokens /auth/listpermtokens

Permanent Tokens are used in tools projects - specificaly 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

Parameter Value
End Point https://api.fundpress.io/auth/listpermtokens
Headers None
Content Type application/json
HTTP Method POST
Return Type JSON
Return Data A list of valid permanent tokens for the user provided

Body

{
    "userId": 8
}
JSON Key Required Description
userId TRUE The id of the user to get the tokens of.

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 - specificaly for calls to the APIs which are embedded in web pages. Can only be deleted by a super admin user.

Service call details.

Parameter Value
End Point https://api.fundpress.io/auth/deletepermtoken
Headers None
Content Type application/json
HTTP Method POST
Return Type Text
Return Data none
Body
{
    "token": "xxxx"
}
JSON Key Required Description
token TRUE The token to be deleted

Login /auth/requestStrategies

Retrieves a list of authentication strategies for an organization.

Service call details.

Parameter Value
End Point https://api.fundpress.io/auth/requestStrategies
Headers None
Content Type application/json
HTTP Method POST
Return Type JSON
Return Data A list of authentication strategies for an organization.
Body
{
    "organization": "ABC Capital Management"
}
JSON Key Required Description
name TRUE The strategy name (unique throughout the system)
type TRUE The strategy type
Response
[
    {
        name: "ABCCapitalManagement",
        type: "saml",
    },
];

Request Password Reset /auth/password-reset

Passwords get forgotten and this is when the reset password functionality can help you out. An email will then be sent to the users email address with further instructions on how to complete the password reset request.

Service call details.

Parameter Value
End Point https://api.fundpress.io/auth/password-reset
Headers X-KSYS-APP
Content Type application/json
HTTP Method POST
Return Type Status Code Only
Return Data none
Body
{
    "userName": "jim.smith"
}
JSON Key Required Description
userName TRUE The userName of whom to create a reset request

Validate Code /auth/validate-code

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

Service call details.

Parameter Value
End Point https://api.fundpress.io/auth/validate-code
Headers X-KSYS-APP
Content Type application/json
HTTP Method POST
Return Type JSON
Return Data none
Body
{
    "passwordRequestId": "XYZ123XYZ",
    "type": "password"
}
JSON Key Required Description
passwordRequestId TRUE A unique ID associated with the password reset
type TRUE The type of request this should be validated against
Response
JSON Key Required Type Description
message FALSE string If the code is valid and no extra steps are required this will return "ok"
error FALSE string If the code is invalid or there is a problem with the request, this field will give more information about the cause
imageRequired FALSE boolean Whether an image is required when setting the users password
messageRequired FALSE boolean Whether a message is required when setting the users password
{
    "imageRequired": true,
    "messageRequired": true
}
{
    "error": "code is invalid"
}
{
    "message": "ok"
}

Password Complexity /auth/password-requirements

Before we are able to update any passwords, 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.

Parameter Value
End Point https://api.fundpress.io/auth/password-requirements
Headers none
Content Type application/json
HTTP Method POST
Return Type JSON
Return Data A list of password requirements
Body
{
    "passwordRequestId": "XYZ123XYZ"
}
JSON Key Required Description
passwordRequestId TRUE A unique ID associated with the password reset
Response
{
    "minLength": 13,
    "maxLength": 128,
    "minLetters": 1,
    "minNumbers": 1,
    "minPunctuation": 0,
    "requireUppercaseAndLowercase": false,
    "limitCharacterRepetition": false,
    "enforcePreviousPasswordCheck": false
}
JSON Key Description
minLength Minimum length
maxLength Maximum length
minLetters Minimum letter characters
minNumbers Minimum number characters
minPunctuation Minimum special characters
requireUppercaseAndLowercase Must contain upper and lower case characters
limitCharacterRepetition Limit the repetition of successive characters
enforcePreviousPasswordCheck Do not allow previous passwords to be used

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

Parameter Value
End Point https://api.fundpress.io/auth/update-password
Headers X-KSYS-APP
Content Type application/json
HTTP Method POST
Return Type Status Code Only
Return Data none
Body
{
    "passwordRequestId": "XYZ123XYZ",
    "password": "newPassword12345",
    "confirmPassword": "newPassword12345",
    "imageId": "212aa7e9-fadf-4cc3-a010-6950c2837a25",
    "message": "A message"
}
JSON Key Required Description
passwordRequestId TRUE A unique ID associated with the password reset
password TRUE The new password
confirmPassword TRUE Confirmation of the new password
imageId FALSE The ID of the assurance image to set (see assurance/getImages)
message FALSE The message to use for assurance

Assurance /auth/assurance

If assurances are enabled for a client, the response to this call will give 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. 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.

Parameter Value
End Point https://api.fundpress.io/auth/assurance
Headers none or X-KSYS-TOKEN
Content Type application/json
HTTP Method POST
Return Type JSON
Return Data See response section
Body
{
    "username": "user12345",
    "clientName": "client1"
}
JSON Key Required Description
username TRUE The username of the user
clientName TRUE The client name
Response
JSON Key Required Type Description
assuranceImageEnabled TRUE boolean Whether the client has enabled image assurance
assuranceMessageEnabled TRUE boolean Whether the client has enabled message assurance
imageId FALSE string The image id of the selected image
image FALSE string Base64 string representation of the image binary
message FALSE string The assurance message
{
    "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.

Parameter Value
End Point https://api.fundpress.io/auth/assurance/getImage
Headers none or X-KSYS-TOKEN
Content Type application/json
HTTP Method POST
Return Type IMAGE or JSON
Return Data See response section
Body
{
    "passwordRequestId": "82989116-fb83-43b6-b305-c60bfd4dd5d6",
    "imageId": "212aa7e9-fadf-4cc3-a010-6950c2837a25",
    "format": "json"
}
JSON Key Required Description
passwordRequestId TRUE A unique ID associated with the password reset
imageId TRUE The ID of an image
format FALSE Format of the response. Supported are json or image
Response

Binary Image

or, if

{
    "format": "json"
}
JSON Key Required Type Description
image FALSE string Base64 string representation of the image binary
{
    "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.

Parameter Value
End Point https://api.fundpress.io/auth/assurance/getImage
Headers none or X-KSYS-TOKEN
Content Type application/json
HTTP Method POST
Return Type JSON
Return Data See response section
Body
{
    "passwordRequestId": "82989116-fb83-43b6-b305-c60bfd4dd5d6",
    "limit": 9
}
JSON Key Required Description
passwordRequestId TRUE A unique ID associated with the password reset
limit FALSE The number of images to be returned.
Response
JSON Key Required Type Description
imageId TRUE string The ID of an image
image FALSE string Base64 string representation of the image binary
{
    "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 for this applicationCode

Service call details.

End Point | https://api.fundpress.io/auth/username-request Headers | X-KSYS-APP Content Type | application/json HTTP Method | POST Return Type | Status Code Only Return Data | none

Body
{
    "email": "jim.smith@jsmithconsulting.com"
}

Update Assurance Details /auth/assurance/update

Updates a user's assurance image and message.

Service call details.

Parameter Value
End Point https://api.fundpress.io/auth/assurance/update
Headers X-KSYS-TOKEN
Content Type application/json
HTTP Method POST
Return Type JSON
Return Data 200 OK
Body
{
    "imageId": "212aa7e9-fadf-4cc3-a010-6950c2837a25",
    "message": "Hello World!"
}

Upsert Users To Impersonate /auth/impersonation/upsert

Service call details.

Parameter Value
End Point https://api.fundpress.io/auth/impersonation/upsert
Headers X-KSYS-TOKEN
Content Type application/json
HTTP Method POST
Return Type JSON
Return Data 200 OK
Body
    {
        "username": "alexander.bell",
        "impersonationListType": "INCLUDE",
        "users": [
            "nikola.tesla",
            "isaac.newton",
            "stephen.hawking",
            "charles.darwin"
        ]
    }
JSON Key Required Description
username TRUE The username of the user able to impersonate the others
impersonationListType TRUE Specifies wether the list is inclusive, exclusive or allowing all users. Accepted values are : "ALL" | "INCLUDE" | "EXCLUDE" | null
users FALSE Array of unique usernames that will either be denied or allowed depending on the impersonationListType

List Users To Impersonate /auth/impersonation/list

Service call details.

Parameter Value
End Point https://api.fundpress.io/auth/impersonation/list
Headers X-KSYS-TOKEN
Content Type application/json
HTTP Method POST
Return Type JSON
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 get all their roles and permissions, and can perform any actions they are allowed to do, apart from impersonating another user.

The user whom gets impersonated will get notified by email of this activity.

Service Call Details

Parameter Value
End Point https://api.fundpress.io/auth/impersonation/impersonate
Headers X-KSYS-TOKEN
Content Type application/json
HTTP Method POST
Return Type Text
Return Data 200 OK
Body
{
    "username": "Alexander Bell"
}

Impersonate a user /auth/impersonation/stopimpersonating

Stops the current impersonation session and switches back to the original user.

Service Call Details

Parameter Value
End Point https://api.fundpress.io/auth/impersonation/stopimpersonating
Headers X-KSYS-TOKEN
Content Type application/json
HTTP Method POST
Return Type Text
Return Data 200 OK
Body
{
}
JSON Key Required Description
userName TRUE The user to impersonate.

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

Parameter Value
End Point https://api.fundpress.io/auth/impersonation/search
Headers X-KSYS-TOKEN
Content Type application/json
HTTP Method POST
Return Type Text
Return Data JSON
Body
{
    "userName": "Bell",
    "start": 0,
    "limit": 10
}
JSON Key Required Description
userName FALSE Filters the list of users by a partial match on userName
limit FALSE The maximum number of items to return
start FALSE The offset used in the query to start
Example response
{
  "total": 2,
  "values": [
    {
        "userName": "Alexander Bell"
    },
    {
        "userName": "Alexandra Bell",
        "impersonating": true
    }
  ]
}

Search for impersonation users /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

Parameter Value
End Point https://api.fundpress.io/auth/impersonation/sessions/search
Headers X-KSYS-TOKEN
Content Type application/json
HTTP Method POST
Return Type Text
Return Data JSON
Body
{
    "impersonator": "Kevin Adkins",
    "userName": "Bell",
    "startDateRange": ["2017-01-01T00:00:00Z", "2017-12-31T23:59:59.999Z"],
    "limit": 10,
    "start": 0
}
JSON Key Required Description
impersonator FALSE The name of the user that is impersonating
userName FALSE Filters the list of sessions by a partial match on userName
startDateRange FALSE Filters the list of sessions by a range match on the impersonation start datetime
limit FALSE The maximum number of items to return
start FALSE The offset used in the query to start
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"
    }
  ]
}
JSON Key Type Description
impersonator string The username of the impersonator
userName string The username of the person being impersonated
startTimestamp datetime Filters the list of sessions by a range match on the impersonation start datetime
stopTimestamp datetime The maximum number of items to return