1.1 Introduction

Securing RESTful APIs is fundamental to the success of any API Strategy or implementation; any approach should include the following three key areas:

  1. Domain of Consideration
  2. Domain of Control
  3. Identity-centric and Holistic View


1. Domain of Consideration

Developing and securing RESTful APIs is more than just applying standards; it is a framework and state of mind that has to be understood and followed jointly by the business owners, IT architects and developers. The API Security framework must be defined at the organisation and business level and should always consider who, how and what users and applications (both internal and external to an organisation) will interact with the APIs. These considerations should be defined at the beginning of any project and driven from a desired business outcome e.g. provide real time information for the public about the closest location and address of a GP.

Illustration of API Security Considerations 

Figure 1: API Security Considerations

2. Domain of Control

The Domain of Control contains the components (defined further in this document) that need to be developed, deployed and work together to provide API security to support:

  • Registered application developer access to the API
  • Authenticated and authorised consuming application access to the API
  • Protected communication between the API and the consuming application to ensure confidentiality and integrity
  • The ability for applications to act on behalf of a customer


3. Identity Centric and Holistic View

The security of APIs should not just be seen as a bounded solution i.e. only the components illustrated in security considerations above, but needs to be seen from a holistic perspective. It needs to incorporate existing enterprise security frameworks where the management and understanding of user identities is core. For example, securing an API that is targeted for a mobile application is not just about applying an OAuth profile, it should take into consideration how mobile devices and applications are managed and secured and how the enterprise security framework (e.g. authentication) can be leveraged.

Illustration of Identity Centric

Figure 2: Identity Centric

People- (or User-) centric security frameworks are key to defining the required access policies and controls for APIs. The management of Identity (this includes users, device, servers and applications) should be central to any API security framework.

1.1.1 Definitions

For this standard the following definitions are used:

  1. Authentication is the process of verifying the identity of a customer (or device) who presents identity credentials and authentication key(s);
  2. Authentication Authority – is a system entity that provides authentication services to ensure only permitted customers (or devices) gain access
  3. Authorisation is the process of verifying that a customer (or device) has the right to perform an action and what they are allowed to access;
  4. Availability is the ability to minimise API downtime by implementing threat protection;
  5. Confidentiality is the ability to ensure information that is sent between Users, Applications and Servers is only visible to those authorised to use it;
  6. Delegation is when a user authorises another user (or device) to serve as his or her representative for a particular task;
  7. Delegated Authorisation is a framework that defines how an owner of a set of resources can grant access (delegate) to a designated user or consuming application to perform actions on some of those resources on the owner’s behalf, but without sharing their credentials;
  8. Federation is the process that allows for the leverage and reuse of identity credentials to multiple Authentication Authorities for authentication and/or Single Sign On;
  9. Integrity is the ability to ensure that information received has not been modified by a third party, also providing non-repudiation services;
  10. Provisioning is the automated or manual service for aggregating and correlating identity data resulting in the creation of user (IT) accounts and the delivery of user meta data used by systems to define access policies and controls for services.
  11. Threat protection is the service for protecting APIs (at the ingress and egress points of an organisation) from known threats (e.g. the OWASP top 10) by preventing misuse or loss of availability. Note: Threat protection should also be addressed at the OS hardening level and should be an integral part of the API software development; 
  12. User Managed Access has been developed to provide a user data delegation model which enables a resource owner to control the authorisation of data sharing and other protected-resource access made between online services on the owner’s behalf or with the owner’s authorisation by an autonomous requesting party;

Note: A customer/user can be internal or external to a Government agency.

1.1.2        Standards for Securing RESTful APIs

The table below captures (current) security standards that should be part of any API Security Strategy, ordered by type. The provisioning standards are included to complete the Identity and Access Standards table. This enables it to be used by architects to select the most appropriate option.


Provides the framework for managing the provisioning of user and their access to APIs e.g. the process for internal or external developers gaining access to API development and publishing services


Service Provisioning Markup Language is an XML based framework for facilitating the exchange of provisioning information (creates, updates and deletes) on user objects (e.g. an LDAP Directory). This is normally implemented to provide Just in Time (Real Time) provisioning.

Although now regarded by most as a legacy standard, it is still supported by most vendors and used by niche service vendors.


System for Cross-domain Identity Management. This is a RESTful API-based framework for Just In Time provisioning and, like SPML, moves away from batch- and delta-based provisioning processes. It uses a RESTful API to manage the provisioning of users.

As SCIM is a REST API framework it should be secured using OAuth.

Federation / Authentication

Provides authentication and Single Sign On services to customers and secure transportation of authentication and authorisation information.


Security Assertion Markup Language (SAML) is an XML-based, open-standard data format for exchanging authentication and authorisation data between parties; in particular, between an identity provider and a service provider.

SAML is seen as complex but is regarded as a high-level security framework.

As it is based on XML, SAML can have high payload overheads and thus can result in performance issues in the mobile application space.

It is still widely used but its uptake is declining. It is included in this standard to support existing New Zealand SAML instances (e.g. education, RealMe).

OpenID Connect

OpenID Connect is an interoperability authentication protocol based on the OAuth 2.0 framework.

This is a relatively recent federation protocol that provides lightweight federation services. It, like SAML, provides SSO services and allows the secure exchange of user authentication data, but it is not as feature rich as SAML.

As it is based on REST/JSON, it is perceived as the Federation service of choice for mobile services.

Delegated Authorisation

Provides a framework for delegating the specified access rights to a 3rd party.

OAuth 1.0a

OAuth 1.0a is derived from the original OAuth 1.0 specification (RFC 5849) which provides a method for client applications to access resources on behalf of a resource owner. It is an authentication framework around the exchange of signed tokens.

It has now been made obsolete by OAuth 2.0.

OAuth 2.0

OAuth 2.0 is an open standard for a delegated authorisation framework. It is not backward compatible with OAuth 1.0, but is modelled on the framework with the objective of providing greater flexibility and defines specific credential (grant) flows.

It is also based on token exchange, with the primary difference being that the tokens are secured by mandating TLS on all communication connections (RFC 6749), where the OAuth 1 tokens are digitally signed.

Authorisation Standards

Provides a framework for controlling access to resources.


The eXtensible Access Control Markup Language standard is XML based and defines a fine-grained attribute-based access control policy language.

It provides an architectural model and policy terminology that can be used to separate out the functions of any authorisation framework.

As it is based on XML it is sometime perceived as a legacy standard, but, from a RESTful API perspective, it provides a fine-grained attribute-based authorisation framework. (RFC 7061)


User-Managed Access is an OAuth-based access management protocol standard.

It builds on OAuth 2.0 to provide additional delegated authorisation capabilities.

Its key focus, for RESTful APIs, is to enable an individual (Resource Owner) to manage and define a set of access control policies that can be managed by an Authorisation Server, which controls access to a set of APIs.


Abbreviated Language For Authorisation defines fine-grained authorisation rules in a JSON-like policy language.

This language helps remove one of the greatest barriers for implementing XACML, which is complexity in writing of the access control policies.

Two (Multi)-factor Authentication

This is a method of confirming a user’s claimed identity (authentication) by using two or more pieces of evidence, relating to something they know, something they have and something they are.


Universal 2nd Factor is an open authentication standard that can be incorporated into an API security framework


Time-based and HMAC-based One-Time Password. These can be used in any of the authentication processes that are part of the process of gaining access to APIs. The requirements for these would be based on business requirements and risk analysis of the information or service being exposed by the API.

These could be used to add a second authentication factor to any existing or proposed authorisation mechanisms.

JSON Security Standards

This is a set of standards that provide security around the exchange of tokens, based on JSON.



A JSON Web Token is designed to be compact and provides trusted information that is used in the authentication process.

Used in API security to pass identity information, specifically by OpenID Connect.


JSON Web Encryption standard provides integrity validation and can be used with or without digital signatures.


JSON Web Signature is a standard for signing JSON, thus providing a level of authority (where it has come from) and integrity, by proving the JWT hasn’t been changed in transit.


JSON Web Algorithm defines the algorithms used for encrypting the JWT.



JSON Web Keys represent the cryptographic key used for encrypting JWT. The algorithms for these are defined in JWA.

Table 1 - API Security Standard

1.1.3        Risks

APIs are another channel into an organisation’s resources and information. Most organisations are accustomed to exposing a web interface, with good control over what information is released via that interface. APIs offer direct, machine to machine access to resources and information, which makes it less obvious when information is incorrectly exposed. It becomes increasingly important for internal business stakeholders to decide what information and resources should be released via this channel, and to whom.

The security risks that APIs introduce will be similar to the traditional risks experienced on any web channel (web sites and web applications), except there is:

  • Increased attack surface due to more ways in, multiple services to potentially exploit 
  • Risk of inadvertently exposing back-end data, back-end architecture and back-end applications

Risks posed by APIs include loss of integrity, confidentiality and availability of data, for example:

  • Loopholes retrieving API resources may offer access to more information than was intended (especially if fields requested are built straight into a DB query)
  • Write operations offer a means of polluting data stores, feeding misinformation into a system
  • Write operations could be used to form a Denial of Service attack by overloading the server or data store
  • Use of wildcards in search fields can shut down APIs and back-end applications
  • Cross site scripting attacks made possible by consuming applications not checking user inputs
  • SQL injection into consuming applications which cause database damage at the API backend
  • Parameter attacks such as HTTP Parameter Pollution (HPP)
  • Man-in-the-middle attacks, modifying API requests or responses leading to data eavesdropping or misinformation insertion
  • Subverting authentication or authorisation mechanisms to spoof messages from legitimate consumers
  • Stealing authentication tokens to obtain information illicitly
  • System information leakage through API error messages revealing details about an API’s construction or underlying system makeup
  • Broken Session IDs, Keys and authentication create exposure to unauthorized access through authentication factors that are not functioning because of poor security design or technology bugs.

1.1.4 Mitigation Approach

API risks need to be mitigated in a number of ways. There is no single off-the-shelf security solution which can be dropped in to address all aspects of API security.  APIs need to be secure by design; security needs to be built in from scratch, and be considered within the context of existing protection mechanisms.

The main areas that API Security covers are:

  1. Identity and Access Management (IdAM) to provide the following services:
  • Authentication
  • Authorisation and delegated authority
  • Federation
  1. Confidentiality
  2. Integrity
  3. Availability and Threat Protection

This ensures that:

  • The consuming application is known and can only get access to API resources they are allowed to
  • Message content has not been tampered with between consumer and provider
  • Resources are reliably from the provider intended when the consuming application made the request
  • The API will be available when needed, and not brought down by attacks from malicious consuming applications

In order to address API security risks, a security framework is needed which encapsulates all the aspects of security listed above.  

Page last updated: 16/12/2016