The CFS public API allows third parties to perform a wide number of functions, including creating new quotations, purchasing policies, performing mid-term adjustments, viewing report data, etc. in this guide we'll go through the process of setting up a new API key.
The required permissions couldn't be simpler, just enable the "API Keys" settings option in the system token editor using the CFS Console, you'll then see a new menu option appear to launch the editor. You can optionally enable edit permissions by checking "+ edit" and password reset permissions by checking "+ pass reset". For the purposes of this guide you will require all 3 permissions enabled.
By default the editor will show you a read-only view of the existing API keys on the system. You can edit the existing items (subject to the +edit permission being granted) by clicking the icon in the top right. To add a new API key simply click the icon in the bottom right of the screen. When you add a new item you automatically enter editing mode.
An API key is formed from a number of parts, some of these are definable and some are automatically set by the system, the definable aspects of the API key are:
Name – the friendly name of this key, for example "Compare the Market" or "GoCompare", etc. defining a friendly name helps you easily identify this key in the future.
Quote Type - all API keys must be bound to a single quote type, this quote type is then used to render the schema and defines which quote type is used when quotations are created. API Keys used for reporting purposes can access multiple quote types, as defined by the System Token but must still be bound to a single quote type for quote creation purposes.
Lead (optional) - when new quotes are created they will be created with this lead. The options are automatically set based on the options you define in Quote Setup -> Leads and change based on the selected quote type automatically.
Access Channels - it is highly recommended that you setup a new unique key for each channel (i.e one for Beta and one for Live), this means the API credentials are sandboxed to a single endpoint and prevents any cross-contamination of test data on your live channel.
Allowed Takeup Outputs - a quotation has 3 outputs - Accept, Refer or Decline, if you wish to allow an integrator access to takeup referred and/or declined quotations you can select that option here. The default (and recommended) option is to allow only Accepted quotes to be taken-up.
ACL - the Access Control List controls which IP addresses are allowed to use api key. It is recommended practice that the list be as verbose as possible and only allow specific, individual IP addresses, but you can also enter a CIDR mask to control IP ranges, or use a single * entry to allow traffic from all locations. To edit the ACL click the icon next to the IP list when it edit mode to bring up a list editor.
Audit - turning on auditing of an API key logs all requests made by the API key in your Request Log, given the verbose nature of these logs it is recommended that auditing be turned on for new API keys until they go-live, at which point it should be disabled to make your log more managable.
Any changes you make whilst in edit mode (including adding new API keys and changes to the ACL) are not applied until you click the icon (top right).
When Audit is enabled you can review activity originating from the API key by selecting "Review activity" in the menu, this is very useful for debugging purposes when integrating with new endpoints.
The credentials you need to pass to the integrator come in 2 parts - firstly the API Key and secondly the Password. Both of these values are automatically assigned and can be accessed via the menu:
View key - The key is the equivelent of the username needed to authenticate this integrator. The key is automatically assigned to new integrators and cannot be changed.
Reset password - due to the nature in which passwords are safely stored within the system it is not possible to view a password after it has been set. Therefore if you need to recover the password the only option is to reset it. Please note - if an API key is restricted to a certain channel (for example Beta only) then you will only be able to reset the password whilst connected to that channel.
A quick note on password security best practices - it is not recommended that an API password be sent via email in plain text (including within attachments), and it's recommended that the password never be sent to integrators using the same method as the key was sent. We would recommended communicating the key via email and then sending the password via Text message or other means.
The required permissions couldn't be simpler, just enable the "API Keys" settings option in the system token editor using the CFS Console, you'll then see a new menu option appear to launch the editor. You can optionally enable edit permissions by checking "+ edit" and password reset permissions by checking "+ pass reset". For the purposes of this guide you will require all 3 permissions enabled.