1.2 Security Reference Architecture

This section describes an API Security Reference Architecture and its component parts to inform the construction of an API security framework.

1.2.1 Actors and Security Functional Capabilities

Identity and Access Management defines the actors (users and devices) who interact with system components that manage and expose APIs. Figure 3 shows a typical model of API components (support stack) and actors. The actors and components are described in Table 2 and Table 3.

 Illustration of API Actors and Core Components

Figure 3: API Actors and Core Components

The green areas highlight internal actors while the yellow areas highlight the external actors.

The components defined remain valid no matter what API architecture (internal, cloud, hybrid) is implemented.


Actors and Devices

External Users

  • Customers - the public, other agencies and partners who use consuming applications to access resources via APIs.
  • External application developers who build software to access resources via APIs


  • PC Browsers running web applications
  • Mobile Devices running apps
  • Servers running systems with server-to server communications


  • Internal API Developers who build APIs
  • Internal Application Developers who build software which accesses resources via APIs
  • Business Owners responsible for the API product(s)
  • Security responsible for ensuring the APIs are secure

Table 2 - Actors and Devices

The core components of an API Security Framework (the development portal, manager and gateway) provide a grouping of functionality. These functions can be delivered with discrete applications, or bespoke code development, via COTS products or through leveraging existing devices that can be configured to provide these functions / services. Note: some of the functionality may overlap or be combined into one or more products depending on the vendor used.

The following lists the functions of a mature API delivery and security framework for an agency that is working with the development community. Together, these functions provide full support for the application developer building and developing consuming applications that will use the API(s) exposed by the agency.

Depending on the requirements of the agency, some of these functions might not be required e.g. if the agency API exposed is purely for public consumption and only allows consuming applications to read information, then only a solution for enforcing threat protection (i.e. Denial of Service) might be required, and this could be delivered using an existing service protection capability. 

Core Components

API Portal

The API Portal often provides the following functions for internal and external application developers:

  • Discovery of APIs
  • Analytics to monitor APIs
  • Access to specifications and descriptions of APIs, including SLAs
  • Social network capability to share and publish ideas

Also supports the development, build and test of consuming applications.

API Manager

The API Manager functions cover:

  • Centralised API administration and governance for API catalogues
  • Management of registration and on-boarding processes for communities of API developers
  • Lifecycle Management of APIs
  • Applying pre-defined security profiles
  • Security policy administration / definition
  • Policy evaluation


API Gateway

The API Gateway capability can provide the following:

  • Act as the API proxy or the host acting as the primary point of access for exposed APIs
  • Enforce threat protection, throttling and quota management
  • Authorisation Services to control access to APIs
  • Authentication Services to ensure only permitted users (internal/external) have access to the API
  • Security Policy enforcement
  • Monitoring and analytics for business and security analysts

API Monitoring and Analytics

Business owners and security specialists need to be able to monitor the use of APIs:

  • Monitor uptake of API services
  • Define when to deprecate an old version
  • Profile usage for business
  • Profile usage for security baselines

This helps adapt to change in usage/demand

Credential Stores

The credential stores are identity and key stores which are used to securely store:

  • Internal and external user objects, and possibly groups
  • API keys and secrets, certificates etc.

These stores are used by the API Gateway for authorisation and authentication services

Table 3 - Core Components

The model can also be split, with the API support stack duplicated – one set to support internal API usage and one set to support external use:

Illustration of Split API Support Stack 

Figure 4: Split API Support Stack

Authentication, authorisation, confidentiality, integrity and availability can be applied across the components in the support stack, depending on component capabilities.

The actual configuration and location of the API functional capabilities will vary depending on individual circumstances (e.g. some capabilities may be internal, some may be in the cloud, where API development is outsourced then ‘internal’ functional stack may belong to the outsourcer etc.). Also, some components might not be required or can be developed in house.

1.2.2 Building Secure APIs

Building in security starts from the ground up, so development of APIs needs to be done with awareness of the API security risks associated with the resources and information being exposed, and with appropriate mitigations in place for these API security risks.

When developing an API is it advisable to carefully consider potential malicious use, especially:

  • PUTs and POSTs – which change internal data and could be used to attack or misinform
  • DELETEs – which could be used to remove the contents of an internal resource repository

Standard secure coding practices are always recommended (see OWASP Secure Coding Principles), in line with NZISM guidance.  But API development should take place with awareness of the:

But it is worth also considering the following where your API accepts input values as parameters:

It is also recommended that a security testing capability be incorporated into the development cycle which provides continuous, repeatable and automated tests to find security vulnerabilities in APIs and web applications during development and testing.

1.2.3 API Security Design Principles

The following are key principles that should be applied when designing API security frameworks:

  1. Design with the objective that the API will eventually be accessible from the public internet, even if there are no plans to do so at the moment
  2. Use a common authentication and authorisation pattern, preferably based on existing security components: avoid creating a bespoke solution for each API
  3. Least Privilege - Access and authorisation should be assigned to API consumers based on the minimal amount of access they need to carry out the functions required
  4. Maximise entropy (randomness) of security credentials by using API Keys rather than username and passwords for API authorisation, as API Keys provide an attack surface that is more challenging for potential attackers
  5. Balance performance with security with reference to key life times and encryption / decryption overheads


Page last updated: 16/12/2016