API Overview & Authentication: API page

API page

This API allows you to …

Link to equivalent system function page.

Supplementary SWAGGER documentation is available here: https://api.catch-e.com/docs/ update to right path

Permissions

Note: This permission and API are not available by default.
Contact your Account Manager to get access to this API.
To run this API, the nominated 'web-services' role needs to be given permission.

If you are not actively using the API, leave the permission off for better security.

Go to Roles / Apis and check on Add permission here.

Authentication

Authenticate with the API before running this API.

HTTP Method

Use the HTTP Method 'METHOD HERE' for consuming this web service.

URL Examples

https://api.staging.catch-e.com/put more here

Body (JSON)

Input Fields (Body) Example

{ "variant_id": "167317", "user_id_client_manager": "10000", "inclusions": [ { "inclusion_code": "IC1", "inclusion_plan_code": "IPC1" }, { "inclusion_code": "IC2", "inclusion_plan_code": "IPC2" } ], "status_flag": "draft"}

Response Details

{ "quote_id": 132657}

| The request was a successful request. |
| 401 - Unauthorized | | |

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Unauthorized", "status": 401, "detail": "Unauthorized"}

| You have not authenticated before running this API or The token_timeout of the current session has passed. You need to authenticate again. |
| 403 - Forbidden | | |

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Forbidden", "status": 403, "detail": "Forbidden"}

| You do not have permissions for this request. Go to System Roles and enter 'web_services' Navigate to the Roles / APIs tab to make sure the permission you need to run this API is checked. |
| 422 - Unprocessable Entity | | |

 "annual_kilometreS": { "isEmpty": "Value is required and can't be empty",

| Input field annual_kilometres is missing. |
| 424 - Failed Dependency | | |

 "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Failed Dependency", "status": 422, "detail": "Upstream service temporarily unavailable. Please retry."}

| The API cannot run at this time. This can happen for a various reasons, for example: service resource limits have been exceeded the system is in maintenance mode |

API Authentication Overview

| 2facode | string | Catch-e two-factor authentication code. | No To access a specific API, your user Role must be found in gbroleapipermissions for the respective gbapipermissions (API function).

Successful Authentication Response

{ "access_token": "aaaaaa/bbbbbb.ccccccc.dddddd", "expires_in": 3600, "token_type": "bearer"}

API Restrictions

Overview

API restrictions control the display of fields in specific table entities for a particular role or user. They also define specific restrict clause predicates injected into the DB table gateway layer of the Zend/Db abstraction library utilised by the API.

Note, user API restrictions DO NOT override the role API restrictions, they simply complement/add to the existing restriction set.

Supported predicates

The following predicates are supported in both the gbroleapirestrictions And gbuserapirestrictions tables

• equalTo
• between
• greaterThan
• greaterThanOrEqualTo
• in
• isNotNull
• isNull
• lessThan
• lessThanOrEqualTo
• like
• notBetween
• notEqualTo
• notIn
• notLike

The data field in the predicate definition can be a string, numeric value or an array of the same.

Note: An array can be stored in the data field using the notation, [ ['value1', 'value2'] ]

Credential handling in the API

Both the permission and restriction values will be captured and encapsulated as claims within the JSON Web Token (JWT) provided during API authentication and renewal. Changes to the permissions/restrictions will only be refreshed on subsequent API calls to authenticate or renew.

Restrictions stored in gbuserroles will be translated into the gbuserapi_restrictions table (where applicable).

API On Request

Note: This API is not configured for external use.
Contact your Account Manager to discuss access to this API.

Authenticate with the API

APIs can only be run by Web Services users.

For each API you want to use, give the Web Services role access to run the selected API.

If you are not actively using an API, leave the permission off for better security.

To check or add access to an API

1. Go to System / Roles and select the 'web_services' role
2. The role will display in the Roles / Details tab
3. Navigate to the Roles / Apis tab to see and edit the role's permissions

API Examples

https://api.catch-e.com/authenticate

https://api..catch-e.com/authenticate

• environment - replace or use a placeholder to run this api in Support, Staging or Test.

Input Fields

Response Details - Successful

{ "access_token": "aaaaaa/bbbbbb.ccccccc.dddddd", "expires_in": 3600, "token_type": "bearer"}

401 - Unauthorized

• "detail": "Unauthorized" — You have not authenticated before running this API or The token_timeout of the current session has passed. You need to authenticate again. #"Authentication Failed - Invalid Username and/or Password. Password is case sensitive."
• "detail": "Authentication Failed - Login suspended" — The user's record is suspended, authentication will not be permitted.
• "detail": "Authentication Failed - Login locked" — The user's record is locked, authentication will not be permitted.

403 - Forbidden

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Forbidden", "status": 403, "detail": "API access is not enabled for the user role"}

| You are trying to authenticate a user that is not configured to use APIs. must be set to 'yes' | |
| 422 - Validation Errors | | | |

 "validation_messages": { "username": { "isEmpty": "Value is required and can't be empty" }

| Pass a valid username. | | |

 "validation_messages": { "username": { "invalidUserFormat": "Invalid username format" }

| Pass a valid username. | | |

 "validation_messages": { "password": { "isEmpty": "Value is required and can't be empty" }

| Pass a valid password. | | |

 "validation_messages": { "2fa_code": { "invalidFormat": "2fa_code must be 6 digits" }

| 2fa must be a 6 digit code. | | |

 "validation_messages": { "token_timeout": { "notDigits": "The input must contain only digits" }

| Token timeout must be a valid digit. maximum allowable timeout is 28800 sec. | |

Troubleshooting

When using Chrome to Authenticate with the API and the following message may displayed.

This is caused by stored password in Chrome for the requested URL.

; To resolve complete the following.

1. Open a Chrome window

2. Select this icon in the top right corner

3. Choose "Settings"

4. Select "Autofill" option from menu on the left of screen

5. Select “Passwords”

6. From the displayed list under “Saved Passwords”, find the ‘Site’ for which the above error is shown

7. Select the icon to the right of the identified ‘Site’

8. Select ‘Remove’

9. The error will now be resolved.

Generate a signon token

Get a signon token for a user to bypass the login process to gain entry to the system. The token can only be used once. The default screen resolution is 1024 * 768.

The Roles / Details "Single Signon" field can be used in conjunction with this service to prevent users from logging into the system directly when single signon is in use and another access method is required.

There are some minor differences in screen behaviour between external and internal users to be aware of, but these differences are also present if users log in directly.

If the user's System / Role "Access Type" is 'external', the screens are different in the following ways;

• The Terms of Use and Privacy Policy links for your business are displayed in the screen footers.
• The Audit Icon is not shown
• Quote notes are not displayed in Red in the header area of the Quotes module.
• Credit Application output files are not selectable in the Quotes / Finance tab.

Permission

The permission for this api is stored in as 'SignonToken:Create'.

Only roles with a stored link to this permission in can run this api. By default 'admin' and 'web-services' have already been stored.

HTTP Method

Use the HTTP Method 'POST' to consume this API.

API

https://api.catch-e.com/gb/signon

https://api..catch-e.com/gb/signon

• environment - replace or use a placeholder to run this api in Support, Staging or Test.

Signon

https://.catch-e.net.au/core/signon.phpo?signon=

https://..catch-e.net.au/core/signon.phpo?signon=

• client - add your own client prefix
• environment - replace or use a placeholder to run this api in Support, Staging or Test.

Headers

Body

• user_login (string) — "Username" -This is the user requiring a single signon token. The user's account must exist, and not be suspended or locked. Yes
• token_timeout (integer) — Sets a timeout for the token (in seconds). If not set, the timeout will default from the user's role. No
• screen_width (integer) — Set the screen width in pixels by entering a valid screen resolution width. Visit Supported Screen Resolutions to see a list of supported widths and heights you can choose from. A width and height must both be specified or the default resolution (1024 * 768) will be applied. If a resolution is specified, the signon will launch a new window, even if the specified resolution is the default (1024 * 768). If no resolution is specified, the signon will remain within the existing window. No
• screenheight (integer) — Set the screen height in pixels by entering a valid screen resolution height. See the notes on screenwidth also. No
• singlesignonrole_flag (string) — Prevents a non-single signon user from getting a token if set to 'yes'. If set to 'no' or not set at all, any user can get a token. A single signon user is one that has a role where the Single Signon checkbox on the System / Roles / Details screen is turned off. No
• creategbuserwiththis_role (string) — Pass this parameter in order to give access to a new user on fly. This flag can have value 'driver' or 'package employee'.If the user is 'suspended' or 'locked' request will fail. If the user already have access this flag will be ignored. No

Body example

{ "user_login": "admin", "token_timeout": 3600, "single_signon_role_flag": "yes", "screen_width": 1024, "screen_height": 1080}

Output example

{ "signon_token": "c63d258e074e29fb5f54954dbbc350513f072f7f", "expires_in": 3600}

401 - Unauthorized

• "detail": "Unauthorized" — You have not authenticated before running this API or The token_timeout of the current session has passed. You need to authenticate again.

422 - Unprocessable Entity

• "detail": "Failed Validation" — User is not enabled for single signon and the api requires this. To enable, remove "singlesignonroleflag": "yes", from your api statement or set it to "no". "singlesignonroleflag": {"userRoleNotSingleSignon": "Specified users role is not single signon"}
• "detail": "Failed Validation" — The user is not known, the user's "Status" is 'locked' or 'suspended' or the user login is 'fbtdec'. "userlogin": { "noRecordFound": "Specified user login is not authorised for signon, locked or is invalid"}
• "detail": "Failed Validation" — The userlogin field is missing or is empty "userlogin": {"isEmpty": "Value is required and can't be empty"}
• "detail": "Failed Validation" — User has a 'webservices' or 'fbtdeclaration' role. "user_login": {"unsupportedRole": "A signon token cannot be generated for the specified user"}
• "detail": "Failed Validation" — User login is for 'admin' (a reserved user). "user_login": { "inArray": "Specified user is not allowed"}
• "detail": "Failed Validation" — You have entered an unsupported width and/or height. "screenwidth": { "notInArray": "Specified value is not a supported screen width" }, "screenheight": { "notInArray": "Specified value is not a supported screen height"}
• "detail": "Failed Validation" — User is suspended or locked. "creategbuserwiththis_role": {"userInvalidStatus": "A signon token cannot be generated for the specified user"}
• "detail": "Failed Validation" — User is not known or does not have an fmdriver record. "creategbuserwiththisrole": {"userRoleMismatch": "A signon token cannot be generated for the specified user"}
• "detail": "Failed Validation" — User does not have an active linked contract. An active contract has a populated "Contract Start" date, is not suspended and "Reg Number" is not 'ORDER'. "creategbuserwiththis_role": {"noLinkedContract": "The specified user does not have an active linked contract"}
• "detail": "Failed Validation" — User's email address is blank. Enter an email address. "creategbuserwiththis_role": {"userInvalidEmail": "The specified user does not have a valid email address"}

Error Code example

{ "validation_messages": { "single_signon_role_flag": { "userRoleNotSingleSignon": "Specified users role is not single signon" } }, "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Unprocessable Entity", "status": 422, "detail": "Failed Validation"}