All you need to know about the Lloyd's API reference architecture, the approach taken to design APIs and the security aspects of the API services.

Architectural Overview

High-Level Logical Model

Web APIs

A server-side web API is a programmatic interface consisting of one or more publicly exposed endpoints to a defined request–response message system, typically expressed in JSON or XML, which is exposed via the web—most commonly by means of an HTTP-based web server.

Rest APIs

Representational state transfer is an architectural pattern for designing APIs. The REST design pattern promotes the reuse of web technologies and features into API designs. The REST design pattern also promotes stateless interactions between the API client and the API implementation. These design patterns and practices allow API implementations to reuse many of the tools and frameworks that have been built over the last 20 years to support web servers. For example, a properly designed REST API should enable the use of an off-the-shelf web caching proxy to increase performance and reduce load on an API implementation.

Market APIs

The London Market will need many APIs to enable integration of all the Market systems into a cohesive whole that support end to end business processes. These APIs will be implemented by many different organisations and these organisations or implementations may change over time. To insulate API consumers (clients) from this complexity we have created two items:

    • API Standards
    • API Gateway

API Standards

The London Market organisations collectively agreed a set of API standards that all APIs provided by the Market for the Market would abide by. These standards are purely technical and do not speak to the business processes that an API might relate to. There are many ways of designing an API even within the REST design pattern. The API standards selects a common subset that will be used for all London Market APIs. The benefit to choosing a common subset is that all APIs provided will then look similar, follow the same approaches and use the same technical choices. This commonality will save all organisation firms significant time in adoption, development and implementation. There are many aspects to the API Standard including:

    • Security
    • Versioning
    • Concurrency
    • Data Representation
    • Filtering
    • Caching
    • Linking
    • Failures
    • URIs

API Gateway

The London Market API Gateway exists as a single common facade for APIs used by the London Market. All Market derived APIs will be presented through this gateway. All calls from API clients to API implementations go through the gateway. This central gateway provides the following advantages:

    • A single web address for all APIs irrespective of backend implementation;
    • A single security model for all APIs independently ensured;
    • Backend implementation details are masked;
    • Central point of contact for API service management issues;
    • Validation of API requests against the API technical contract;
    • Central point of control over released APIs;
    • Two additional separate testing environments;
    • Central notification about new/changed APIs;
    • Central notification about maintenance periods.

The API Gateway does NOT:

    • Translate or modify in any way the request or response payloads;
    • Validate business data;
    • Perform any business logic or take any business action;
    • Notify any other business system as a side effect;
    • Important: All request made to an API must pass through the API Gateway.


There are three separate and completely independent LIMOSS Common Services environments. These environments support the same API Gateway features and LIMOSS tickets.

Sandbox - The lowest and least constrained environment.

This is where developers can access test versions of APIs (test harnesses) that implement the API spec but do not require special terms and conditions to use. Most of the development of the application takes place in this environment. Visit Registration and Onboarding page to see the diagram of the onboarding journey, explaining what objectives are to be achieved at each stage. This environment must not contain real data.

Pre-Prod - This is the pre-Live or pre-Production enviroment where SIT, UAT and other tests on developed application can be performed. You can test your application against actual API implementations.

This environment should not contain real data.

Note: Some platforms may have multiple instances in this environment used for various testing purposes. For example there may be an instance for UAT (UI) and there may be an instance for performance testing. It is likely that there needs to be specific pre-configuration steps on each instance (e.g. setting up accounts) in order to enable testing on each one.

Production - This environment is reserved for live systems in Production (where Production API consumers can connect to Production API Providers). This environment may also have an instance which can serve a system that holds real Market data (for example for live support systems).

Security Overview

The API Standards specify a common security pattern that all APIs must use.

The API gateway acts as a policy enforcement point (PEP) between the API client and the API implementation. Requests that come from unauthenticated or unauthorised application or accounts are screened by the gateway and do not reach to the API implementation.

Only registered and released APIs can be accessed via the API Gateway. Client must present tokens over secure channels to gain access to an API through the API gateway.

The API Gateway delegates some parts of Authentication to Secure Token Services (STS) and delegates some parts of Authorization to the back end implementation.


All requests to the API Gateway must use HTTPS (TLS 1.1 or 1.2).

Authentication Overview

Application authentication and Account authentication are distinct parts of the authentication process. The Application (or service) is required to authenticate itself to the API Gateway. This is performed as part of the HTTPS call to invoke the service.

The API Gateway has a X509 certificate that it uses to prove that it is actually the API gateway. The client has its own x509 certificate that it presents over the HTTPS/ TLS request to the API-GW. In this way both the client and server mutually authenticate each other during the HTTPS setup. Possession of the private key and x509 certificate, and successful negotiation of the TLS channel constitute authentication of the application to the API Gateway.

All calls to APIs are performed by applications or services. The application or service must be acting on behalf of a user account or a system account. The user (or system) account that the application is calling the API on-behalf-of must also be authenticated to the API Gateway. User and System accounts are both identified by a principle that is an email address.

External Secure Token Services (STSs) are used to validate account identities and their respective credentials (e.g. passwords).

The Common Services Azure Active Directory is a general STS that is trusted by the API-Gateway to validate accounts for all domains. Other STSs may be configured into the gateway with limited token granting scope (e.g. just for a single domain).

The Application or Service must obtain a Java Web Token (JWT) for the account from a STS. The JWT must specify the API Gateway as the target of he JWT, along with a number of other specific claim requirements.

The JWT must list the email address as the principle of the JWT in a specified claim.

The Common Services Azure Active Directory can only provide JWTs for accounts that are known to it. This is the reason that accounts need to be invited into the Common Services Azure Active Directory.

A JWT signed by a trusted STS supplied in the Authentication header of the HTTPS request constitutes authentication of the account to the API Gateway. The API-GW will check the signature of the JWT upon receipt.

The API Gateway will reject any request that does not match a known API and the above requirements.

Authorisation Information

If the client certificate is confirmed by TLS and the JWT has been signed by a trusted STS and validated, then the API Gateway proceeds to the authorisation step.

The API Gateway checks that the x509 Certificate Canonical Name (CN) is registered in Common Services against an organisation, and that the organisation is registered to use the API specified in that request.

The API Gateway will confirm that the JWT is for a user known to the Common Services Azure Active Directory and that the email principle matches one of the email patterns that has been registered against the x509 certificate.

If any of the above restrictions are not met then the API Gateway will reject the request.

Any further authorisation is then delegated to the API implementation. The API Implementation may use the account principle to determine if the request is allowed given the full URI, the state of the backend system and any other rules it may implement. The API Implementation is supplied with the user principle email address, the CN of the certificate used in the request.

Security Prerequisites

For a client application to be able to call an API, a number of preconditions must be met:

    • Organisation Common Services Signup
    • Account invitation
    • App Registration
    • Organisation API Signup
    • Client Cert configuration
    • Token acquisition

Organisation Common Services Signup

The organisation that owns and runs the application or service that is going to call the API must first register with Common Services. This registration involves signing various T’s and C’s. The details of how to sign up for common services can be found here:

Account Invitation

The accounts that are going to be used when accessing the API need to be invited to the common services active directory. The authorized users can make use of the LIMOSS self service portal to raise tickets to get users invited. Users can only be invited by an authorized user from their own organisation. If you are planning to provide an application that third party organisation can access then those organisation must also register with Common Services and have their users invited into the common services directory.

App Registration

The client application must be registered with the Common Services Azure Active Directory. There are two types of Azure Active Directory application registrations Web App and Native App.

Web App – This is for applications using the OAuth2.0 Code Grant Flow, that is for interactive logins. This grant flow is used where the application does not know the username or the password. The user is prompted by the STS and can supply both to Azure Active Directory (AAD) directly.

Native App – This is for applications using the OAuth2.0 Password Grant Flow, that is non-interactive logins. This grant flow is used where the application knows the username and the password and can supply both to Azure Active Directory (AAD) directly.

If an application supports both user interaction authenticated API calls and offline service calls then the application will need two App registrations.

Postman is a common testing client that can be used by a developer or tester to call an API. Postman does not support interactive logins so you will need a Native App registration to test with Postman.

Organisation API Signup

The organisation that is going to deploy and run the application will need to register to call the APIs required by that application. Registering to use an API is done by creating a ticket with LIMOSS service desk here.

Each API as its own terms and conditions that may vary and your organisation may need to setup a service agreement directly with the API implementor.

Client Cert Configuration

The organisation that is going to deploy and run the application will need to procure a x509 certificate that has been signed by a CA that is included in the Microsoft Trusted Root Programme.

Once the certificate has been obtained then it must be registered with in the API Gateway.

Token Acquisition

Every request to the API Gateway must include a Java Web Token (JWT):

    • JWTs are created by Secure Token Sevices, such as Azure Active Directory;
    • Before the actual API request can be made the application must request a JWT from a STS;
    • Depending on whether the applcation is acting as a native app or a web app a different request will be made to the STS;
    • The STS may return an access token (that is used in the API Request) and a refresh token;
    • The refresh token can be used by the application to get a new JWT if the access token expires;
    • The token sent in the API Request to the API Gateway must be of type "User_Impersonation";
    • The token that a web application gets as a result of a normal user authentication (login) results in a normal JWT in this case;
    • The Application will need make a subsequent request to Azure Active Dirtectory to request an "on behalf of" JWT.