Security Phase Research
Raw Data
This file contains raw search retrieval results or agent logs. The content below shows the original markdown source.
---
layout: raw-data.njk
title: Security Phase Research
---
# Security Phase Research Results
**Date**: 2025-11-03
**Purpose**: Comprehensive research for API Security Phase section of NZ API Standard
**Total searches**: 7
**Total results**: ~158
---
## Search 1: OAuth 2.0 Authentication and Authorization (Part B)
**Query**: "API security authentication authorization OAuth"
**Type**: semantic_search_filtered
**Filters**: part="B"
**Limit**: 40
**Results**: 40
### Key Findings
1. **OAuth 2.0 Framework** - Industry standard for API security, regarded as synonymous with securing APIs
2. **OAuth 2.0 Grant Types** - Multiple grant types for different patterns (authorization code, client credentials, CIBA)
3. **OpenID Connect** - Authentication protocol based on OAuth 2.0 framework
4. **API Gateway Integration** - Most gateways provide OAuth 2.0 support and can connect to authorization servers
5. **Security Tokens** - Access tokens, refresh tokens, authorization codes
6. **Client Credentials** - Client ID and client secret for application authentication
### Results
1. **OAuth** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part15-para1-l40))
- Part: B | Type: list | Level: N/A
- Content: "==OAuth== Open Authorization"
- Tags: [definition, definitions]
- Score: 0.9129
- **Note**: Primary definition of OAuth
2. **OAuth 2.0 Framework Context** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part3-para2))
- Part: B | Type: para | Level: N/A
- Content: "Authorisation and authentication are intrinsically linked inside the OAuth 2.0 framework, which in itself is regarded as synonymous with securing APIs. OAuth 2.0 uses its own terminology, which is worth becoming familiar with when adopting an OAuth 2.0 approach."
- Tags: [definition, definitions]
- Score: 0.9096
- **Note**: Establishes OAuth 2.0 as the standard approach
3. **OAuth 2.0 Authorization Framework RFC** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part12-tb1-tr1-td1-l2))
- Part: B | Type: list | Level: N/A
- Content: "The OAuth 2.0 Authorization Framework"
- Tags: [definition, definitions]
- Score: 0.9095
- **Note**: Reference to RFC 6749
4. **OAuth 2.1 Authorization Framework** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part13-para1-tb1-tr4-td1))
- Part: B | Type: table | Level: N/A
- Content: "The OAuth 2.1 Authorization Framework"
- Tags: []
- Score: 0.9080
- **Note**: Next generation OAuth framework
5. **OAuth 2.0 Framework Extensions** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part12-tb1-tr2-td1-l2))
- Part: B | Type: list | Level: N/A
- Content: "The OAuth 2.0 Authorization Framework:"
- Tags: [definition, definitions]
- Score: 0.9057
6. **OAuth 2.0 Pushed Authorization Requests** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part13-para1-tb1-tr7-td1))
- Part: B | Type: table | Level: N/A
- Content: "OAuth 2.0 Pushed Authorization Requests"
- Tags: []
- Score: 0.8966
7. **OAuth 2.0 Client Authentication** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part9-para7-tb1-tr10-td1-l2))
- Part: B | Type: list | Level: N/A
- Content: "OAuth 2.0 clients applications can use client IDs and client secrets to authenticate to the services (for example, token generation, user information and access revoke)."
- Tags: []
- Score: 0.8948
8. **OAuth 2.0 Comprehensive Approach** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part3-section2-para1))
- Part: B | Type: para | Level: 2
- Content: "OAuth 2.0 provides a more comprehensive and extensible approach to security than some of the basic authentication and authorisation mechanisms. Based on security tokens, it can be used for delegated authority such as enabling a mobile application to act on behalf of its user. For more details see [Appendix C](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part8)."
- Tags: []
- Score: 0.8945
- **Note**: Highlights OAuth 2.0 advantages
9. **OAuth 2.0 RFC 6749** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part12-tb1-tr1-td1))
- Part: B | Type: table | Level: N/A
- Content: "RFC 6749 The OAuth 2.0 Authorization Framework"
- Tags: [definition, definitions]
- Score: 0.8940
10. **OAuth Services Management** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part7-section5-para4-2))
- Part: B | Type: para | Level: N/A
- Content: "OAuth services and the management of client ID and a client secrets (for applications)"
- Tags: []
- Score: 0.8904
11. **OAuth Authorization Server** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part9-section1-para2-2))
- Part: B | Type: para | Level: N/A
- Content: "an OAuth authorisation server"
- Tags: []
- Score: 0.8897
12. **OAuth 2.0 as Delegated Authorization Framework** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part3-section2-para2))
- Part: B | Type: para | Level: 2
- Content: "The IT industry perceives the need for any production quality API security framework to be based on OAuth 2.0. In reality OAuth 2.0 is a delegated authorisation framework, but it provides the foundations on which secure services can be built in order to provide the complete security solution."
- Tags: []
- Score: 0.8886
- **Note**: Important clarification on OAuth 2.0 role
13. **OAuth 2.0 Assertion Framework** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part12-tb1-tr7-td1-l2))
- Part: B | Type: list | Level: N/A
- Content: "Assertion Framework for OAuth 2.0 Client Authentication and Authorization Grants"
- Tags: [definition, definitions]
- Score: 0.8885
14. **OAuth Server Definition** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part3-section2-para4-3))
- Part: B | Type: para | Level: 3
- Content: "OAuth server / authorisation server provides a security token server / infrastructure for managing tokens. It is responsible for issuing:"
- Tags: [definition, definitions]
- Score: 0.8883
15. **API Gateway OAuth Support** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part3-section5-para19))
- Part: B | Type: para | Level: 2
- Content: "API gateways have been mentioned previously in the context of API protection. Most API gateways on the market provide support for OAuth 2.0 and can also provide authorisation (and authentication) services via a direct connection to:"
- Tags: []
- Score: 0.8878
16. **OAuth 2.0 JWT Secured Authorization Request** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part13-para1-tb1-tr1-td1))
- Part: B | Type: table | Level: N/A
- Content: "OAuth 2.0 JWT Secured Authorization Request"
- Tags: []
- Score: 0.8877
17. **Client Secret** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part9-para7-tb1-tr7))
- Part: B | Type: table | Level: N/A
- Content: "**Client secret** Also provided when the OAuth client application is registered. This is used with the client ID when exchanging an authorisation code for an access token. Required: When implementing an OAuth 2.0 model that supports authorisation code flow."
- Tags: []
- Score: 0.8874
18. **OAuth 2.0 Rich Authorization Requests** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part13-para1-tb1-tr6-td1))
- Part: B | Type: table | Level: N/A
- Content: "OAuth 2.0 Rich Authorization Requests"
- Tags: []
- Score: 0.8868
19. **Authentication Techniques Figure** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part3-section1-fig13-det1))
- Part: B | Type: figure | Level: N/A
- Content: "Figure 13 lists the following authentication techniques that can be used to secure APIs and where they are used: Developer authentication — used to log in to the API portal Anonymous — not recommended to use Multi-factor authentication: User name and password — not recommended for public facing APIs, useful in development / training environments API keys — recommended to use for all APIs, used for application authentication (not human) Certificates — used for: consuming application (B2B only) to API gateway, OAuth 2.0 client to authorisation server, API gateway to backend systems OAuth2 and security tokens — recommended to use for internal and external production APIs OpenID Connect — recommended to use where there is an OpenID Connect provider."
- Tags: [figures, substantive_review, should-or-may, good-practice, standards_review]
- Score: 0.8862
- **Note**: CRITICAL - Key recommendations for authentication methods
20. **OpenID Connect Protocol** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part6-para2-tb1-tr19-td2-l1))
- Part: B | Type: list | Level: N/A
- Content: "An interoperability authentication protocol based on the OAuth 2.0 framework."
- Tags: []
- Score: 0.8862
21. **OAuth 2.0 Resource Indication** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part12-tb1-tr21-td2))
- Part: B | Type: table | Level: 3
- Content: "This document specifies an extension to the OAuth 2.0 Authorization Framework defining request parameters that enable a client to explicitly signal to an authorisation server about the identity of the protected resource(s) to which it is requesting access."
- Tags: []
- Score: 0.8861
22. **Client Secret Definition** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part9-para7-tb1-tr7-td1))
- Part: B | Type: table | Level: N/A
- Content: "**Client secret** Also provided when the OAuth client application is registered. This is used with the client ID when exchanging an authorisation code for an access token."
- Tags: []
- Score: 0.8852
23. **Token Security Risks** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part11-section7-para1))
- Part: B | Type: para | Level: 2
- Content: "Securing OAuth flows relies on the exchange of tokens between consuming applications and API backend servers. There is always the threat of these tokens being obtained illicitly, losing confidentiality and integrity of message content, or the integrity of the sender of the token. This risk also applies to the transferring of API keys."
- Tags: []
- Score: 0.8848
24. **OAuth 2.0 Authorization Server Metadata** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part12-tb1-tr17-td1-l2))
- Part: B | Type: list | Level: N/A
- Content: "OAuth 2.0 Authorization Server Metadata"
- Tags: [definition, definitions]
- Score: 0.8841
25. **Pattern 8: CIBA Authentication** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part2-section9-det8-para1))
- Part: B | Type: para | Level: N/A
- Content: "The recommended authentication and authorisation model is vendor or internally developed API gateway capability — OAuth 2.0 grant type: Client Initiated Backchannel Authentication (CIBA) with OpenID Connect and without PKCE."
- Tags: [patterns, substantive_review]
- Score: 0.8834
- **Note**: Specific pattern recommendation
26. **OAuth 1.0a (Obsolete)** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part6-para2-tb1-tr20))
- Part: B | Type: table | Level: N/A
- Content: "OAuth 1.0a Derived from the original OAuth 1.0 specification (Request for Comments (RFC) 5849) that 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."
- Tags: []
- Score: 0.8832
27. **OAuth 2.0 Device Authorization Grant** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part12-tb1-tr18-td1-l2))
- Part: B | Type: list | Level: N/A
- Content: "OAuth 2.0 Device Authorization Grant"
- Tags: [definition, definitions]
- Score: 0.8812
28. **Pattern 6: Authorizing Consuming Application** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part2-section9-det6))
- Part: B | Type: figure | Level: N/A
- Content: "2.9.6. Pattern 6: Authorising a consuming application The most appropriate authentication and authorisation models are: API keys vendor or internally developed API gateway capability — OAuth 2.0 grant types: client credentials: without OpenID Connect and without PKCE — Recommended API gateway proprietary."
- Tags: [patterns, substantive_review, good-practice, should-or-may, standards_review]
- Score: 0.8810
- **Note**: Pattern for application authentication
29. **Authorization Code Flow** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part8-section1-det1))
- Part: B | Type: figure | Level: N/A
- Content: "8.1.1. Authorisation code Use for internal users or where the customer is the resource owner, your agency controls the resource server, but the authorisation server is not owned by the agency or is elsewhere within the organisation. The authorisation server provides the authorisation code (grant) to the client application once the resource owner has approved the request. The client application then uses this to request the access token. The authorisation server validates the client application using the client ID and client secret. The client application has to store these credentials securely. The client application authenticates to the authorisation server via its TLS certificate and call-back URL. Useful if the API requires a customer of a client application to authorise access to a protected resource provided by the API. **Recommended to use** The most secure OAuth flow. Use for public facing APIs for customer authorisation patterns. Use for pattern 1: internal use only. Use the state attribute to link request and response. It is now recommended to include PKCE in this flow."
- Tags: [should-or-may, good-practice, standards_review]
- Score: 0.8800
- **Note**: RECOMMENDED - Most secure OAuth flow with PKCE
30. **OAuth 1.0a Definition** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part6-para2-tb1-tr20-td2))
- Part: B | Type: table | Level: N/A
- Content: "Derived from the original OAuth 1.0 specification (Request for Comments (RFC) 5849) that 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."
- Tags: []
- Score: 0.8792
31. **Authorization Patterns** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part3-section5-para2))
- Part: B | Type: para | Level: 2
- Content: "In the authentication section the concepts of OAuth were introduced, and a number of authentication patterns were defined. This section focuses on authorisation and provides additional patterns that work with OAuth or provides an alternative."
- Tags: []
- Score: 0.8790
32. **Authentication Options Figure** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part3-section1-fig13))
- Part: B | Type: figure | Level: 2
- Content: "Figure 13: Authentication options "
- Tags: [figures, substantive_review, should-or-may, good-practice, standards_review]
- Score: 0.8786
- **Note**: Visual guide to authentication options
33. **OAuth Assertion Framework** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part12-tb1-tr7))
- Part: B | Type: table | Level: 2
- Content: "RFC 7521 Assertion Framework for OAuth 2.0 Client Authentication and Authorization Grants Common framework for OAuth 2.0 to interact with other identity systems using an assertion and to provide alternative client authentication mechanisms."
- Tags: [definition, definitions]
- Score: 0.8784
34. **Authentication Requirement** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part3-section1-para1))
- Part: B | Type: para | Level: 2
- Content: "When securing APIs, authentication is required to identify the consumers and / or consuming applications that want to access or consume an API. Authentication enables the API provider to identify all consumers of an API and to confirm that the consumer requesting access is who they say they are. This does not automatically authorise them to access the APIs or the underlying resources."
- Tags: [must-or-shall, good-practice, standards_review]
- Score: 0.8780
- **Note**: MANDATORY - Authentication is required
35. **Client Secret Usage** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part9-para7-tb1-tr7-td1-l2))
- Part: B | Type: list | Level: N/A
- Content: "Also provided when the OAuth client application is registered. This is used with the client ID when exchanging an authorisation code for an access token."
- Tags: []
- Score: 0.8775
36. **OAuth 2.0 Industry Adoption** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part3-para3))
- Part: B | Type: para | Level: 1
- Content: "As the OAuth 2.0 framework is a commonly accepted approach to the securing of modern APIs (large companies like Google, Microsoft and Twitter use it), this section also covers an introduction to OAuth 2.0."
- Tags: []
- Score: 0.8772
37. **Pushed Authorization Requests Detail** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part13-para1-tb1-tr7-td2))
- Part: B | Type: table | Level: N/A
- Content: "Pushed Authorization Requests (PAR) enable OAuth clients to push the payload of an authorisation request directly to the authorisation server in exchange for a request URI value, which is used as reference to the authorisation request payload data in a subsequent call to the authorisation endpoint via the user agent."
- Tags: []
- Score: 0.8768
38. **OAuth 2.0 Simple Reference** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part6-para2-tb1-tr21-td1))
- Part: B | Type: table | Level: N/A
- Content: "OAuth 2.0"
- Tags: []
- Score: 0.8762
39. **OAuth 2.0 Device Grant RFC** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part12-tb1-tr18-td1))
- Part: B | Type: table | Level: 3
- Content: "RFC 8628 OAuth 2.0 Device Authorization Grant"
- Tags: [definition, definitions]
- Score: 0.8755
40. **API Security Part Title** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part1-title))
- Part: B | Type: part | Level: 1
- Content: "1. API security"
- Tags: []
- Score: 0.8755
---
## Search 2: API Security Design Principles
**Query**: "API security design principles"
**Type**: semantic_search
**Limit**: 30
**Results**: 30
### Key Findings
1. **Security Design Principles Section** - Dedicated section on security design principles (1.5.1)
2. **Security First Principle** - Build security into the API when being developed
3. **Security by Design** - APIs need to be secure by design with security built in from scratch
4. **Common Authentication Pattern** - Use common authentication and authorization patterns
5. **Content Validation** - Validate content of all incoming messages
### Results
1. **API Security Design Principles Heading** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part1-section5-h1))
- Part: B | Type: heading | Level: 2
- Content: "1.5.1. API security design principles"
- Tags: []
- Score: 0.9758
- **Note**: Main section for security design principles
2. **Security Design Principles Introduction** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part1-section5-para10))
- Part: B | Type: para | Level: 2
- Content: "The following key principles should be applied when designing API security frameworks."
- Tags: [should-or-may, standards_review]
- Score: 0.9490
- **Note**: Introduction to key principles
3. **API Design Principles (Part C)** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section2-h3))
- Part: C | Type: heading | Level: 2
- Content: "1.2.3. API design principles"
- Tags: []
- Score: 0.9424
4. **API Security Part Title** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part1-title))
- Part: B | Type: part | Level: 1
- Content: "1. API security"
- Tags: []
- Score: 0.9125
5. **Building Secure APIs** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part1-section5-title))
- Part: B | Type: section | Level: 2
- Content: "1.5. Building secure APIs"
- Tags: []
- Score: 0.9028
6. **API Security Considerations Figure** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part1-section1-fig1-title))
- Part: B | Type: figure | Level: 3
- Content: "Figure 1: API security considerations"
- Tags: [figures, substantive_review]
- Score: 0.9019
7. **API Security Reference** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part1-section1-fig2-det1-para1-2))
- Part: B | Type: para | Level: 5
- Content: "API security"
- Tags: [figures, substantive_review]
- Score: 0.9004
8. **API Design Section** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section2-title))
- Part: C | Type: section | Level: 2
- Content: "1.2. API design"
- Tags: []
- Score: 0.8991
9. **Security First Principle** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part1-section5-para10-2))
- Part: B | Type: para | Level: 3
- Content: "Security first — build security into the API when being developed."
- Tags: []
- Score: 0.8981
- **Note**: Key principle - security first
10. **API Guidelines Part B Title** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#h1))
- Part: B | Type: root | Level: 0
- Content: "API guidelines — Part B: API security 2022"
- Tags: []
- Score: 0.8964
11. **Part B Introduction** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#para1))
- Part: B | Type: root | Level: 0
- Content: "Learn about API (Application Programming Interface) security reference architecture and the technical details for implementing API security."
- Tags: [reference-examples-apis, substantive_review]
- Score: 0.8943
12. **API Security Reference** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part1-section1-para6-3))
- Part: B | Type: para | Level: 3
- Content: "API security."
- Tags: []
- Score: 0.8943
13. **Good Practice Principles** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part2-para1))
- Part: A | Type: para | Level: 1
- Content: "These are a set of principles that are considered good practice when designing, implementing and operating APIs. The New Zealand Government Digital Service Design Standard provides a wider perspective and set of principles that should also influence the design of APIs and the services they support."
- Tags: [should-or-may, good-practice, standards_review]
- Score: 0.8937
- **Note**: Links to broader design principles
14. **API Design and Development Part** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-title))
- Part: C | Type: part | Level: 1
- Content: "1. API design and development"
- Tags: []
- Score: 0.8930
15. **Secure by Design** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part1-section3-para5))
- Part: B | Type: para | Level: 2
- Content: "API risks need to be mitigated in a number of ways. There is no single off-the-shelf security solution that 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:"
- Tags: []
- Score: 0.8922
- **Note**: CRITICAL - Secure by design principle
16. **Designing an API** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section2-h7))
- Part: C | Type: heading | Level: 2
- Content: "1.2.4. Designing an API"
- Tags: []
- Score: 0.8921
17. **Security Component in APIs** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section2-para15))
- Part: C | Type: para | Level: 2
- Content: "Every API will have a security component. It is important to recognise that this is not only authentication and authorisation for access to an API, it also includes threat protection (Distributed Denial of Service (DDoS), Structured Query Language (SQL) Injection, Cross Site Scripting, and so on) as well as availability and Quality of Service (QoS). When designing and developing APIs it is often cost effective to create a common framework that handles security for all APIs. See [Part B: API security 2022](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/) for more details."
- Tags: [definition, definitions, must-or-shall, should-or-may, good-practice, standards_review]
- Score: 0.8901
- **Note**: Every API will have security component
18. **API Design Section (Part A)** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part4-section1-h3))
- Part: A | Type: heading | Level: 2
- Content: "4.1.3. API design"
- Tags: []
- Score: 0.8892
19. **Business Principles** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part1-section9-para3-8))
- Part: A | Type: para | Level: 3
- Content: "Principles — In order to incorporate all-of-government thinking into API development it is useful to have a set of business principles that should influence the way APIs are built and their usefulness over time."
- Tags: [good-practice, should-or-may, standards_review]
- Score: 0.8872
20. **Building Security from Ground Up** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part1-section5-para1))
- Part: B | Type: para | Level: 2
- Content: "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."
- Tags: []
- Score: 0.8865
21. **Security Team Responsibility** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part1-section4-para3-tb1-tr3-td2-l4))
- Part: B | Type: list | Level: 6
- Content: "* Security responsible for ensuring the APIs are secure"
- Tags: [reference-examples-apis, substantive_review]
- Score: 0.8835
22. **API Security Use Case** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part5-title))
- Part: B | Type: part | Level: 1
- Content: "5. API security use case"
- Tags: []
- Score: 0.8834
23. **Security Framework Need** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part1-section3-para7))
- Part: B | Type: para | Level: 2
- Content: "In order to address API security risks, a security framework is needed that encapsulates all these aspects of security."
- Tags: []
- Score: 0.8825
24. **API Concepts** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part1-title))
- Part: A | Type: part | Level: 1
- Content: "1. API concepts"
- Tags: []
- Score: 0.8804
25. **API Security Standards Table** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part6-para2-tb1-caption))
- Part: B | Type: table | Level: 3
- Content: "Table 3: API security standards"
- Tags: []
- Score: 0.8792
26. **API Security Considerations Figure Detail** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part1-section1-fig1))
- Part: B | Type: figure | Level: 2
- Content: "Figure 1: API security considerations "
- Tags: [figures, substantive_review]
- Score: 0.8788
27. **Security Framework Definition** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part1-section1-para3))
- Part: B | Type: para | Level: 2
- Content: "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 — for example, provide real time information for the public about the closest location and address of a general practitioner."
- Tags: [must-or-shall, standards_review]
- Score: 0.8787
- **Note**: MANDATORY - Framework must be defined
28. **OWASP Secure Coding Principles (Part C)** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part10-para1-6))
- Part: C | Type: para | Level: 2
- Content: "[OWASP Secure Coding Principles — OWASP](https://wiki.owasp.org/index.php/Security_by_Design_Principles)"
- Tags: [links-out-external, substantive_review]
- Score: 0.8776
29. **OWASP Secure Coding Principles (Part B)** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part16-para1-6))
- Part: B | Type: para | Level: 2
- Content: "[OWASP Secure Coding Principles — OWASP](https://wiki.owasp.org/index.php/Security_by_Design_Principles)"
- Tags: [definition, definitions, links-out-external, substantive_review]
- Score: 0.8776
30. **API Security Reference Architecture** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part1-section4-para1))
- Part: B | Type: para | Level: 2
- Content: "This section describes an API security reference architecture and its component parts to inform the construction of an API security framework. It is important to note that REST, gRPC, GraphQL and AsyncAPI are different architectural models for building synchronous and asynchronous APIs that can leverage the security controls (for example, OAuth 2.0 and OpenID Connect) defined in these guidelines, but they all have their own intrinsic security models (for example, throttling consideration in GraphQL) which are not covered in these guidelines."
- Tags: [reference-examples-apis, substantive_review, good-practice, must-or-shall, standards_review]
- Score: 0.8771
- **Note**: Reference architecture description
---
## Search 3: TLS HTTPS Transport Security
**Query**: "TLS HTTPS transport security"
**Type**: semantic_search
**Limit**: 30
**Results**: 30
### Key Findings
1. **TLS 1.3 Requirement** - All communications to/from an API MUST be over TLS 1.3 or higher
2. **Certificate Validation** - Consuming applications MUST validate TLS certificate chain
3. **Disable Older Versions** - TLS 1.0, 1.1 and SSL should be disabled
4. **Token Protection** - Tokens must be protected in transit (TLS) and storage (encryption)
5. **Mutual TLS (MTLS)** - For B2B and high-security scenarios
### Results
1. **TLS Definition** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part15-para1-l64))
- Part: B | Type: list | Level: 2
- Content: "==TLS== Transport Layer Security (superseded SSL)"
- Tags: [definition, definitions]
- Score: 0.9297
- **Note**: Primary TLS definition
2. **MTLS Definition** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part15-para1-l37))
- Part: B | Type: list | Level: 2
- Content: "==MTLS== Mutual Transport Layer Security"
- Tags: [definition, definitions]
- Score: 0.8709
3. **Token Protection in Transit** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part9-para7-tb1-tr2-td2-l2))
- Part: B | Type: list | Level: 5
- Content: "The token is protected both in transit (TLS) and in storage (encryption)."
- Tags: []
- Score: 0.8687
4. **Token Protection Requirement** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part9-para7-tb1-tr1-td2-l2))
- Part: B | Type: list | Level: 5
- Content: "* The token is protected both in transit (TLS) and in storage (encryption)."
- Tags: []
- Score: 0.8631
5. **Communication Security Requirements** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part11-section7-para2-tb1-tr2-td2))
- Part: B | Type: table | Level: 5
- Content: "* Communication security. * Use TLS 1.3 with a cipher suite that includes DHE or ECDHE. * The client application must validate: * the TLS certificate chain * check the certificate revocation list stored locally in a file or LDAP server."
- Tags: [must-or-shall, standards_review]
- Score: 0.8611
- **Note**: MANDATORY - TLS 1.3 with specific cipher suites
6. **Communications Security Section** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part11-section1))
- Part: B | Type: section | Level: 1
- Content: "11.1. Communications security (confidentiality) — Required All communications to or from an API must be over TLS 1.3 or higher. Other versions of TLS and Secure Sockets Layer (SSL) should be disabled. This provides a recognised level of confidentiality that covers all communications between all components. The consuming application must validate the TLS certificate chain when making requests to protected resources, including checking the Certificate Revocation List (CRL)."
- Tags: [must-or-shall, standards_review]
- Score: 0.8575
- **Note**: MANDATORY - Core TLS requirement
7. **TLS Certificate Chain Validation** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part11-section7-para2-tb1-tr2-td2-l4))
- Part: B | Type: list | Level: 6
- Content: " * the TLS certificate chain"
- Tags: []
- Score: 0.8575
8. **TLS Version Deprecation Note** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part12-tb1-tr2-td2-l2))
- Part: B | Type: list | Level: 4
- Content: "**Note:** RFC 8996 deprecates Transport Layer Security (TLS) 1.0 and 1.1 and recommends 1.2 or ideally 1.3 in OAuth 2.0 implementations."
- Tags: [definition, definitions]
- Score: 0.8511
9. **MTLS Back Channel** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part3-section2-para12))
- Part: B | Type: para | Level: 2
- Content: "The back channel link is normally secured using Mutual Transport Layer Security (MTLS), but the initial flow to obtain the code token is over Transport Layer Security (TLS) and in certain architectures can be intercepted in a man-in-the-middle attack."
- Tags: []
- Score: 0.8475
10. **Mutual TLS Pattern** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part2-section9-det5-para1-1))
- Part: B | Type: para | Level: 4
- Content: "mutual TLS (certificates)"
- Tags: [patterns, substantive_review]
- Score: 0.8461
11. **Mutual TLS Pattern (Duplicate)** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part2-section9-det1-para1-1))
- Part: B | Type: para | Level: 4
- Content: "mutual TLS (certificates)"
- Tags: [patterns, substantive_review]
- Score: 0.8461
12. **Content Encryption and TLS** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part11-section3-para2))
- Part: B | Type: para | Level: 2
- Content: "Content encryption enables all or part of a JavaScript Object Notation (JSON) payload to be readable only by the target consumer(s). This is useful where the content being carried by the API is sensitive, and the API request or response transits multiple stopping points. While TLS protects the payload in transit, it only applies to each point to point connection between components (for example, mobile app to API gateway). If transit components are not totally under the provider's control, it can be worthwhile performing body encryption. It may be sensible to encrypt credit card details passed between consumer and provider backend systems."
- Tags: []
- Score: 0.8440
13. **TLS 1.3 Requirement** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part11-section1-para1))
- Part: B | Type: para | Level: 2
- Content: "All communications to or from an API must be over TLS 1.3 or higher. Other versions of TLS and Secure Sockets Layer (SSL) should be disabled. This provides a recognised level of confidentiality that covers all communications between all components."
- Tags: [must-or-shall, should-or-may, standards_review]
- Score: 0.8432
- **Note**: MANDATORY - TLS 1.3 or higher
14. **Communication Over TLS Note** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part9-section1-para12-ex1-exl1))
- Part: B | Type: example | Level: 4
- Content: "**Note:** The communication must be over TLS."
- Tags: [must-or-shall, standards_review]
- Score: 0.8425
15. **Communication Over TLS Note (Duplicate)** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part9-section1-para12-ex1))
- Part: B | Type: example | Level: 3
- Content: "**Note:** The communication must be over TLS."
- Tags: [must-or-shall, standards_review]
- Score: 0.8425
16. **Token Disclosure Mitigation** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part11-section7-para2-tb1-tr2))
- Part: B | Type: table | Level: 4
- Content: "Token disclosure — man-in-the-middle attack — the access token is passed in clear text with no hashing, signing or encryption * Communication security. * Use TLS 1.3 with a cipher suite that includes DHE or ECDHE. * The client application must validate: * the TLS certificate chain * check the certificate revocation list stored locally in a file or LDAP server."
- Tags: [must-or-shall, standards_review]
- Score: 0.8410
17. **TLS for Trusted Subsystem** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part7-section2-para4))
- Part: B | Type: para | Level: 2
- Content: "API security is provided by the application (web) server acting as a trusted subsystem with TLS links to the backend API server. The application / web server invokes the backend and provides the required user ID information, which can be in the form of a session token."
- Tags: [good-practice, standards_review]
- Score: 0.8404
18. **TLS for Clear Text Passwords** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part7-section2-para5-3))
- Part: B | Type: para | Level: 3
- Content: "passwords would be in clear text — if direct authentication is used, TLS would be required to secure all communications"
- Tags: [good-practice, standards_review]
- Score: 0.8401
19. **STS Definition** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part15-para1-l63))
- Part: B | Type: list | Level: 2
- Content: "==STS== Security Token Service"
- Tags: [definition, definitions]
- Score: 0.8372
20. **Validate TLS Certificate Chain** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part11-section7-para2-tb1-tr4-td2-l3))
- Part: B | Type: list | Level: 6
- Content: "* Validate TLS certificate chain when accessing resource server."
- Tags: []
- Score: 0.8346
21. **SSL Definition** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part15-para1-l61))
- Part: B | Type: list | Level: 2
- Content: "==SSL== Secure Sockets Layer"
- Tags: [definition, definitions]
- Score: 0.8320
22. **API Key Protection Over TLS** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part7-section3-para8))
- Part: B | Type: para | Level: 2
- Content: "However, the risk is that anyone with a copy of the API key can use it as though they were the legitimate consuming application. Hence, all communications should be over TLS, to protect the key in transit. The onus is on the application developer to properly protect their copy of the API key."
- Tags: [should-or-may, standards_review]
- Score: 0.8301
23. **TLS for Assertions** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part3-section4-para12))
- Part: B | Type: para | Level: 2
- Content: "To address the risk of forged or stolen assertions, it is recommended that all communication is over TLS and tokens are at a minimum signed for authentication."
- Tags: [should-or-may, good-practice, to-review, standards_review]
- Score: 0.8292
- **Note**: Recommended for assertions - arguably mandatory
24. **Security Token Service Description** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part12-tb1-tr19-td2))
- Part: B | Type: table | Level: 3
- Content: "Defines a protocol for a lightweight HTTP and JSON-based Security Token Service (STS) — covering requests of tokens from an authorisation server."
- Tags: [definition, definitions]
- Score: 0.8284
25. **TLS 1.3 Cipher Suite** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part11-section7-para2-tb1-tr2-td2-l2))
- Part: B | Type: list | Level: 6
- Content: "* Use TLS 1.3 with a cipher suite that includes DHE or ECDHE."
- Tags: []
- Score: 0.8281
26. **OAuth Framework TLS Reliance** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part9-para3))
- Part: B | Type: para | Level: 1
- Content: "The OAuth framework (RFC 6749 and 6750) relies heavily on TLS for the security of the bearer token. The following RFCs offer additional integrity and confidentiality capability that can be applied to the bearer token (access token):"
- Tags: []
- Score: 0.8259
27. **TLS Certificate Validation Requirement** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part11-section1-para2))
- Part: B | Type: para | Level: 2
- Content: "The consuming application must validate the TLS certificate chain when making requests to protected resources, including checking the Certificate Revocation List (CRL)."
- Tags: [must-or-shall, standards_review]
- Score: 0.8198
- **Note**: MANDATORY - Certificate validation
28. **Token Transit Protection** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part9-para7-tb1-tr2-td2))
- Part: B | Type: table | Level: 4
- Content: "Required: The token is protected both in transit (TLS) and in storage (encryption). Recommended: The lifetime of the token is set to 24 hours."
- Tags: []
- Score: 0.8187
29. **Security Field (OpenAPI)** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part6-section1-para1-ex1-pf1-pfl18))
- Part: C | Type: example | Level: 5
- Content: " security:"
- Tags: []
- Score: 0.8185
30. **Security Field (AsyncAPI)** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part5-para3-ex3-pf1-pfl28))
- Part: C | Type: example | Level: 4
- Content: " security:"
- Tags: []
- Score: 0.8185
---
## Search 4: Threat Protection and Validation
**Query**: "threat protection validation"
**Type**: semantic_search
**Limit**: 30
**Results**: 30
### Key Findings
1. **Threat Protection Definition** - Service for protecting APIs from known threats (OWASP Top Ten)
2. **Threat Risks Table** - Comprehensive table of threats and mitigations (Table 5)
3. **Input Validation** - Validate content of all incoming messages
4. **Threat Protection at OS Level** - Should be addressed at operating system hardening level
5. **OWASP Guidelines** - Reference to OWASP for secure coding practices
### Results
1. **Threat Protection** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part4-para2-4))
- Part: B | Type: para | Level: 2
- Content: "Threat protection"
- Tags: []
- Score: 0.9198
2. **Availability and Threat Protection Section (4.2)** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part4-section2-title))
- Part: B | Type: section | Level: 2
- Content: "4.2. Availability and threat protection"
- Tags: []
- Score: 0.8760
3. **Availability and Threat Protection Section (11.6)** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part11-section6-title))
- Part: B | Type: section | Level: 2
- Content: "11.6. Availability and threat protection"
- Tags: []
- Score: 0.8728
4. **Threat Protection Definition** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part1-section2-para3-l12))
- Part: B | Type: list | Level: 3
- Content: "==Threat protection== The service for protecting APIs (at the ingress and egress points of an organisation) from known threats (for example, [OWASP (Open Web Application Security Project) Top Ten](https://owasp.org/www-project-top-ten/)) by preventing misuse or loss of availability."
- Tags: [definition, definitions, links-out-external, substantive_review]
- Score: 0.8714
- **Note**: Primary definition with OWASP reference
5. **Content Validation Principle** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part1-section5-para10-8))
- Part: B | Type: para | Level: 3
- Content: "Validate the content of all incoming messages, ensuring communications are secured (in other words, encrypted) and apply threat protection policies (for example, injection and throttling)."
- Tags: []
- Score: 0.8673
6. **Threat Mitigation Column** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part11-section7-para2-tb1-thr1))
- Part: B | Type: table | Level: 4
- Content: "Threat Mitigation"
- Tags: []
- Score: 0.8669
7. **Threat Protection at OS Level** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part1-section2-para3-ex1))
- Part: B | Type: example | Level: 3
- Content: "**Note:** Threat protection should also be addressed at the operating system hardening level and should be an integral part of the API software development."
- Tags: [definition, definitions, should-or-may, standards_review]
- Score: 0.8579
8. **Threat Protection at OS Level (Duplicate)** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part1-section2-para3-ex1-exl1))
- Part: B | Type: example | Level: 4
- Content: "**Note:** Threat protection should also be addressed at the operating system hardening level and should be an integral part of the API software development."
- Tags: [definition, definitions, should-or-may, standards_review]
- Score: 0.8579
9. **Availability and Threat Protection Full Section** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part11-section6))
- Part: B | Type: section | Level: 1
- Content: "11.6. Availability and threat protection Table 5 lists threat risk types and some recommended approaches to help mitigate these. Table 5: Threat risks and mitigations..."
- Tags: [should-or-may, good-practice, standards_review]
- Score: 0.8550
- **Note**: Full section with comprehensive threat table
10. **OWASP Input Validation Cheat Sheet** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part1-section5-para8-1))
- Part: B | Type: para | Level: 3
- Content: "[OWASP Input Validation Cheat Sheet — OWASP](https://cheatsheetseries.owasp.org/cheatsheets/Input_Validation_Cheat_Sheet.html): a summary of input risks and mitigations"
- Tags: [links-out-external, substantive_review]
- Score: 0.8503
11. **Availability and Threat Detection** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part1-section3-para5-4))
- Part: B | Type: para | Level: 3
- Content: "availability and threat detection"
- Tags: []
- Score: 0.8468
12. **Protection API for Token Validation** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part3-section3-para11-1))
- Part: B | Type: para | Level: 3
- Content: "protection API — used by resource servers for getting authorisation-request tokens and validating access tokens"
- Tags: []
- Score: 0.8439
13. **Threat Mitigation Approaches** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part11-section6-para1))
- Part: B | Type: para | Level: 2
- Content: "Table 5 lists threat risk types and some recommended approaches to help mitigate these."
- Tags: []
- Score: 0.8406
14. **REST Security Cheat Sheet** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part1-section5-para5-3))
- Part: B | Type: para | Level: 3
- Content: "[REST Security Cheat Sheet — OWASP](https://cheatsheetseries.owasp.org/cheatsheets/REST_Security_Cheat_Sheet.html): REST-specific risks and how to prevent them — for example, input validation"
- Tags: [links-out-external, substantive_review]
- Score: 0.8400
15. **Table 5: Threat Risks and Mitigations** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part11-section6-para1-tb1))
- Part: B | Type: table | Level: 3
- Content: "Table 5: Threat risks and mitigations Threat Mitigation (OWASP) Exposure of inappropriate API methods to access services. * Protect and limit (allow list) the HTTP methods (GET, PUT, and so on) exposed. * Validate method(s) for session token / API key. Denial of Service (DoS) attacks * Throttle access to all exposed APIs. * Monitor use to indicate possible DoS attacks. Malicious input, injection attacks and fuzzing * Validate input secure parsing and strong typing. * Validate incoming content-type application / JSON. * Validate JSON content. * Validate XML (schema and format). * Scan attachments. * Produce valid HTTP return code. * Validate response type. Cross-site request forgery Use tokens with state and nonce parameters. Cross-site scripting attacks Validate input."
- Tags: []
- Score: 0.8389
- **Note**: CRITICAL - Comprehensive threat mitigation table
16. **Table 5 Caption** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part11-section6-para1-tb1-caption))
- Part: B | Type: table | Level: 4
- Content: "Table 5: Threat risks and mitigations"
- Tags: []
- Score: 0.8371
17. **OAuth 2.0 Threat Model RFC** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part12-tb1-tr4))
- Part: B | Type: table | Level: 2
- Content: "RFC 6819 OAuth 2.0 Threat Model and Security Considerations Security considerations for OAuth beyond those in the OAuth 2.0 specification, based on a comprehensive threat model for the OAuth 2.0 protocol."
- Tags: [definition, definitions]
- Score: 0.8369
18. **Threat Mitigation Header (OWASP)** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part11-section6-para1-tb1-thr1))
- Part: B | Type: table | Level: 4
- Content: "Threat Mitigation (OWASP)"
- Tags: []
- Score: 0.8369
19. **API Threat Protection Requirements** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part3-section1-para11))
- Part: A | Type: para | Level: 2
- Content: "To protect an agency's resources, the API component should perform threat protection and quality of service (QoS) functions. This could be in the form of 'throttling' requests, schema validation and common vector attack protection (Structured Query Language (SQL) injection, Cross Site Scripting). This functionality should not be seen as a replacement for other defences, but an augmentation to those defences."
- Tags: [definition, definitions, should-or-may, must-or-shall, good-practice, standards_review]
- Score: 0.8366
- **Note**: Threat protection as augmentation to defenses
20. **OAuth Threat Model RFC Reference** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part12-tb1-tr4-td1))
- Part: B | Type: table | Level: 3
- Content: "RFC 6819 OAuth 2.0 Threat Model and Security Considerations"
- Tags: [definition, definitions]
- Score: 0.8355
21. **Threat Column Header** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part11-section6-para1-tb1-thr1-th1))
- Part: B | Type: table | Level: 5
- Content: "Threat"
- Tags: []
- Score: 0.8336
22. **Threat Header (Token Threats)** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part11-section7-para2-tb1-thr1-th1))
- Part: B | Type: table | Level: 5
- Content: "Threat"
- Tags: []
- Score: 0.8336
23. **Table 6: Token Threat Mitigation** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part11-section7-para2-tb1))
- Part: B | Type: table | Level: 3
- Content: "Table 6: Token threat mitigation Threat Mitigation Token manufacture or modification — fake tokens and man-in-the-middle attacks) Digital signing of tokens like JWS with JWT, or attaching a Message Authentication Code (MAC). Token disclosure — man-in-the-middle attack..."
- Tags: [must-or-shall, standards_review]
- Score: 0.8325
- **Note**: Token-specific threat mitigation
24. **Threat Protection Context** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part4-section2-para1))
- Part: B | Type: para | Level: 2
- Content: "Availability in this context covers threat protection to minimise API downtime, looks at how threats against exposed APIs can be mitigated using basic design principles and how to apply protection against specific risks and threats."
- Tags: []
- Score: 0.8316
25. **Validate Response Type** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part11-section6-para1-tb1-tr3-td2-l7))
- Part: B | Type: list | Level: 6
- Content: "* Validate response type."
- Tags: []
- Score: 0.8308
26. **OAuth Threat Model List Entry** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part12-tb1-tr4-td1-l2))
- Part: B | Type: list | Level: 4
- Content: "OAuth 2.0 Threat Model and Security Considerations"
- Tags: [definition, definitions]
- Score: 0.8280
27. **API Gateway Threat Protection** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part5-section1-para5-1))
- Part: A | Type: para | Level: 3
- Content: "security — offering authentication and authorisation services. Using threat protection capability to protect backend systems against common vector attacks such as SQL injection, Cross Site Scripting and Cross Site Forgery. The API gateway is essentially the Policy Enforcement Point (PEP)"
- Tags: [definition, definitions, good-practice, standards_review]
- Score: 0.8279
28. **Malicious Input Mitigations** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part11-section6-para1-tb1-tr3))
- Part: B | Type: table | Level: 4
- Content: "Malicious input, injection attacks and fuzzing * Validate input secure parsing and strong typing. * Validate incoming content-type application / JSON. * Validate JSON content. * Validate XML (schema and format). * Scan attachments. * Produce valid HTTP return code. * Validate response type."
- Tags: []
- Score: 0.8263
29. **Threat Assessment Early in Lifecycle** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part4-section2-para7-1))
- Part: B | Type: para | Level: 3
- Content: "threat assessment — early on in the API development lifecycle"
- Tags: []
- Score: 0.8260
30. **Token Threat Mitigation Section** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part11-section7-title))
- Part: B | Type: section | Level: 2
- Content: "11.7. Token threat mitigation"
- Tags: []
- Score: 0.8260
---
## Search 5: Mandatory Requirements (Part B)
**Query**: "API requirements standards"
**Type**: semantic_search_filtered
**Filters**: tags=["must-or-shall"], part="B"
**Limit**: 50
**Results**: 0
### Key Findings
**NO RESULTS** - The query was too broad. The must-or-shall tag appears inline with other content rather than as standalone requirement statements. More specific searches are needed to capture mandatory requirements.
### Notes for Drafting
- Need to extract mandatory requirements from searches 1-4 and 6-7 based on must-or-shall tags
- Look for language patterns: "must", "shall", "required", "is required"
- TLS 1.3 requirement found in search 3
- Authentication requirement found in search 1
- Framework definition requirement found in search 2
---
## Search 6: Good Practice Security Content
**Query**: "API security"
**Type**: semantic_search_filtered
**Filters**: tags=["good-practice"]
**Limit**: 30
**Results**: 16
### Key Findings
1. **Common Security Framework** - Cost effective to create common framework for all APIs
2. **API Keys Recommended** - For all APIs, especially public APIs
3. **API Gateway Security Role** - Offering authentication, authorization, threat protection
4. **Privacy and Security Assessments** - Should be done at each development stage
5. **Secure Coding Practices** - OWASP guidelines
### Results
1. **Security Component in Every API** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section2-para15))
- Part: C | Type: para | Level: 2
- Content: "Every API will have a security component. It is important to recognise that this is not only authentication and authorisation for access to an API, it also includes threat protection (Distributed Denial of Service (DDoS), Structured Query Language (SQL) Injection, Cross Site Scripting, and so on) as well as availability and Quality of Service (QoS). When designing and developing APIs it is often cost effective to create a common framework that handles security for all APIs. See [Part B: API security 2022](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/) for more details."
- Tags: [definition, definitions, must-or-shall, should-or-may, good-practice, standards_review]
- Score: 0.9264
- **Note**: CRITICAL - Common framework for security
2. **TLS for Trusted Subsystem** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part7-section2-para4))
- Part: B | Type: para | Level: 2
- Content: "API security is provided by the application (web) server acting as a trusted subsystem with TLS links to the backend API server. The application / web server invokes the backend and provides the required user ID information, which can be in the form of a session token."
- Tags: [good-practice, standards_review]
- Score: 0.9122
3. **Security Reference Architecture** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part1-section4-para1))
- Part: B | Type: para | Level: 2
- Content: "This section describes an API security reference architecture and its component parts to inform the construction of an API security framework. It is important to note that REST, gRPC, GraphQL and AsyncAPI are different architectural models for building synchronous and asynchronous APIs that can leverage the security controls (for example, OAuth 2.0 and OpenID Connect) defined in these guidelines, but they all have their own intrinsic security models (for example, throttling consideration in GraphQL) which are not covered in these guidelines."
- Tags: [reference-examples-apis, substantive_review, good-practice, must-or-shall, standards_review]
- Score: 0.9025
4. **API Gateway Security Functions** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part5-section1-para5-1))
- Part: A | Type: para | Level: 3
- Content: "security — offering authentication and authorisation services. Using threat protection capability to protect backend systems against common vector attacks such as SQL injection, Cross Site Scripting and Cross Site Forgery. The API gateway is essentially the Policy Enforcement Point (PEP)"
- Tags: [definition, definitions, good-practice, standards_review]
- Score: 0.8932
5. **Authentication Requirement** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part3-section1-para1))
- Part: B | Type: para | Level: 2
- Content: "When securing APIs, authentication is required to identify the consumers and / or consuming applications that want to access or consume an API. Authentication enables the API provider to identify all consumers of an API and to confirm that the consumer requesting access is who they say they are. This does not automatically authorise them to access the APIs or the underlying resources."
- Tags: [must-or-shall, good-practice, standards_review]
- Score: 0.8923
6. **Risk Mitigation with OWASP** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part4-section2-para6))
- Part: B | Type: para | Level: 2
- Content: "As mentioned in [section 1.3. Risks](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part1-section3), there are various types of risk that impact APIs. This includes threats to availability as well as confidentiality and integrity. Many threats can be mitigated as indicated in [section 1.3.1. Mitigation approach](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part1-section3-h1) and good secure coding practices using [OWASP guidelines](https://owasp.org/www-project-top-ten/)."
- Tags: [definition, definitions, links-out-external, substantive_review, good-practice, standards_review]
- Score: 0.8919
7. **API Keys Recommendation** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part7-section3-para9-ex1))
- Part: B | Type: example | Level: N/A
- Content: "**Note:** API keys are **recommended** as they provide a level of security to public APIs that can help protect sites from screen scraping or provide the required information to throttle, or possibly bill, access to data."
- Tags: [should-or-may, good-practice, standards_review]
- Score: 0.8907
- **Note**: RECOMMENDED for all public APIs
8. **API Keys Recommendation (Duplicate)** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part7-section3-para9-ex1-exl1))
- Part: B | Type: example | Level: N/A
- Content: "**Note:** API keys are **recommended** as they provide a level of security to public APIs that can help protect sites from screen scraping or provide the required information to throttle, or possibly bill, access to data."
- Tags: [good-practice, should-or-may, standards_review]
- Score: 0.8907
9. **API Standards Consideration** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part7-para2))
- Part: C | Type: para | Level: 1
- Content: "In addition to the security standards captured in [Part B: API security 2022](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/), table 7 captures (current) API and web standards that should be considered as part of any API strategy."
- Tags: [should-or-may, good-practice, standards_review]
- Score: 0.8841
10. **Data Protection Importance** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part2-section7-para1))
- Part: A | Type: para | Level: 1
- Content: "APIs are used extensively for passing information on, so it is important to consider the information privacy and sensitivity aspects of data being passed to and from APIs to ensure that data is protected adequately."
- Tags: [should-or-may, good-practice, must-or-shall, standards_review]
- Score: 0.8832
11. **Threat Protection Functions** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part3-section1-para11))
- Part: A | Type: para | Level: 2
- Content: "To protect an agency's resources, the API component should perform threat protection and quality of service (QoS) functions. This could be in the form of 'throttling' requests, schema validation and common vector attack protection (Structured Query Language (SQL) injection, Cross Site Scripting). This functionality should not be seen as a replacement for other defences, but an augmentation to those defences."
- Tags: [definition, definitions, should-or-may, must-or-shall, good-practice, standards_review]
- Score: 0.8789
12. **Authentication Techniques Figure** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part3-section1-fig13-det1))
- Part: B | Type: figure | Level: N/A
- Content: "Figure 13 lists the following authentication techniques that can be used to secure APIs and where they are used: Developer authentication — used to log in to the API portal Anonymous — not recommended to use Multi-factor authentication: User name and password — not recommended for public facing APIs, useful in development / training environments API keys — recommended to use for all APIs, used for application authentication (not human) Certificates — used for: consuming application (B2B only) to API gateway, OAuth 2.0 client to authorisation server, API gateway to backend systems OAuth2 and security tokens — recommended to use for internal and external production APIs OpenID Connect — recommended to use where there is an OpenID Connect provider."
- Tags: [figures, substantive_review, should-or-may, good-practice, standards_review]
- Score: 0.8761
- **Note**: CRITICAL - Comprehensive authentication recommendations
13. **API Keys Section Full** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part7-section3))
- Part: B | Type: section | Level: 1
- Content: "7.3. API keys authentication — Recommended API keys are a digital authentication mechanism..."
- Tags: [should-or-may, to-review, must-or-shall, good-practice, standards_review]
- Score: 0.8705
- **Note**: Full section on API keys
14. **Privacy and Security Section** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part2-section7))
- Part: A | Type: section | Level: 1
- Content: "2.7. Privacy and sensitivity aware APIs are used extensively for passing information on, so it is important to consider the information privacy and sensitivity aspects of data being passed to and from APIs to ensure that data is protected adequately. Consideration should be given as to whether a privacy impact assessment and / or a security risk assessment is appropriate for the API during each stage of development, from concept through to implementation..."
- Tags: [must-or-shall, should-or-may, good-practice, standards_review]
- Score: 0.8683
- **Note**: Privacy and security assessments at each stage
15. **Privacy Assessments for Sensitive Data** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part2-section7-para6))
- Part: A | Type: para | Level: 1
- Content: "However, privacy and security considerations become hugely important if the API is providing programmatic access to private, personal information. In this situation, it may be appropriate to do regular assessments, especially early in the concept phase to ensure any privacy or security constraints are understood before design."
- Tags: [must-or-shall, should-or-may, good-practice, standards_review]
- Score: 0.8670
16. **Privacy and Security Risk Assessments** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part2-section7-para2))
- Part: A | Type: para | Level: 1
- Content: "Consideration should be given as to whether a privacy impact assessment and / or a security risk assessment is appropriate for the API during each stage of development, from concept through to implementation."
- Tags: [should-or-may, must-or-shall, good-practice, standards_review]
- Score: 0.8669
- **Note**: Assessments at each development stage
---
## Search 7: Authentication Patterns (Part B)
**Query**: "authentication"
**Type**: semantic_search_filtered
**Filters**: tags=["patterns"], part="B"
**Limit**: 40
**Results**: 12
### Key Findings
1. **8 Authentication Patterns** - Defined patterns for different authentication scenarios
2. **Pattern Recommendations** - Specific OAuth grant types and methods for each pattern
3. **Common Authentication Pattern** - Recommended to use common patterns vs bespoke
4. **Decoupled Flow (Pattern 8)** - CIBA for decoupled authentication
5. **Pattern 6: Application Authentication** - Client credentials or API keys
### Results
1. **Most Appropriate Models (Pattern 4)** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part2-section9-det4-para1))
- Part: B | Type: para | Level: N/A
- Content: "The most appropriate authentication and authorisation models are:"
- Tags: [patterns, substantive_review]
- Score: 0.8860
2. **Most Appropriate Models (Pattern 1)** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part2-section9-det1-para1))
- Part: B | Type: para | Level: N/A
- Content: "The most appropriate authentication and authorisation models are:"
- Tags: [patterns, substantive_review]
- Score: 0.8860
3. **Most Appropriate Models (Pattern 7)** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part2-section9-det7-para1))
- Part: B | Type: para | Level: N/A
- Content: "The most appropriate authentication and authorisation models are:"
- Tags: [patterns, substantive_review]
- Score: 0.8860
4. **Most Appropriate Models (Pattern 6)** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part2-section9-det6-para1))
- Part: B | Type: para | Level: N/A
- Content: "The most appropriate authentication and authorisation models are:"
- Tags: [patterns, substantive_review]
- Score: 0.8860
5. **Most Appropriate Models (Pattern 5)** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part2-section9-det5-para1))
- Part: B | Type: para | Level: N/A
- Content: "The most appropriate authentication and authorisation models are:"
- Tags: [patterns, substantive_review]
- Score: 0.8860
6. **Pattern Quick Reference Introduction** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part2-section9-para1))
- Part: B | Type: para | Level: N/A
- Content: "The following provides a quick reference to identify the most appropriate authentication and authorisation model to use for the patterns defined. The models are explained in detail in subsequent sections."
- Tags: [patterns, substantive_review]
- Score: 0.8858
7. **Pattern 3: API Keys** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part2-section9-det3-para1))
- Part: B | Type: para | Level: N/A
- Content: "The most appropriate authentication and authorisation model is API keys."
- Tags: [patterns, substantive_review]
- Score: 0.8758
8. **Common Authentication Pattern Principle** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part1-section5-para10-3))
- Part: B | Type: para | Level: 3
- Content: "Use a common authentication and authorisation pattern, preferably based on existing security components: avoid creating a bespoke solution for each API."
- Tags: [patterns, substantive_review]
- Score: 0.8737
- **Note**: CRITICAL - Use common patterns, avoid bespoke
9. **Pattern 8: Decoupled Flow** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part2-section8-para1))
- Part: B | Type: para | Level: N/A
- Content: "In a traditional flow, the customer or end user is redirected to an authentication page. In pattern 8 and shown in figure 12, the authentication and consent process is delegated to an authentication device of the end user. This process is performed via a back channel with a request and response. This flow decouples the authentication device from the traditional flow. In this model the consuming application or client can initiate the authentication and consent of an end user via an out-of-band mechanism."
- Tags: [patterns, substantive_review]
- Score: 0.8728
10. **Decoupled Flow Figure** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part2-section8-fig12-src1))
- Part: B | Type: figure | Level: N/A
- Content: ""
- Tags: [patterns, figures, substantive_review]
- Score: 0.8686
11. **Developer Authentication Figure** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part2-section2-fig6-src1))
- Part: B | Type: figure | Level: N/A
- Content: ""
- Tags: [patterns, figures, substantive_review]
- Score: 0.8639
12. **Pattern 8: CIBA Recommendation** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part2-section9-det8-para1))
- Part: B | Type: para | Level: N/A
- Content: "The recommended authentication and authorisation model is vendor or internally developed API gateway capability — OAuth 2.0 grant type: Client Initiated Backchannel Authentication (CIBA) with OpenID Connect and without PKCE."
- Tags: [patterns, substantive_review]
- Score: 0.8627
- **Note**: Pattern 8 specific recommendation
---
## Summary of Security Phase Research
### Mandatory Requirements Identified
1. **Authentication Required** - Authentication is required to identify consumers and applications ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part3-section1-para1))
2. **TLS 1.3+ Required** - All communications must be over TLS 1.3 or higher ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part11-section1))
3. **TLS Certificate Validation** - Consuming applications must validate TLS certificate chain ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part11-section1-para2))
4. **Security Framework Definition** - API security framework must be defined at organization and business level ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part1-section1-para3))
5. **Communication Over TLS** - All API communications must be over TLS ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part9-section1-para12-ex1))
6. **TLS Cipher Suites** - Must use TLS 1.3 with DHE or ECDHE cipher suite ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part11-section7-para2-tb1-tr2-td2))
### Strong Elevation Candidates (should→MUST)
1. **OAuth 2.0 for Production APIs** - "OAuth2 and security tokens — recommended to use for internal and external production APIs" ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part3-section1-fig13-det1))
2. **API Keys for All APIs** - "API keys — recommended to use for all APIs" ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part3-section1-fig13-det1))
3. **Common Authentication Pattern** - Avoid bespoke solutions for each API ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part1-section5-para10-3))
4. **TLS for All Communications** - "all communication is over TLS" ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part3-section4-para12)) - annotated as "arguably mandatory"
5. **Security Design Principles** - Should be applied when designing security frameworks ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part1-section5-para10))
6. **Threat Protection** - Should be addressed at OS hardening level and in development ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part1-section2-para3-ex1))
7. **Privacy and Security Assessments** - Should be done at each development stage ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part2-section7-para2))
8. **Authorization Code Flow with PKCE** - "It is now recommended to include PKCE in this flow" ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part8-section1-det1))
### Key Topics Covered
1. **OAuth 2.0 Framework** - Authorization framework, grant types, tokens, flows
2. **OpenID Connect** - Authentication protocol based on OAuth 2.0
3. **Transport Security** - TLS 1.3+, certificate validation, cipher suites, MTLS
4. **Threat Protection** - OWASP Top Ten, input validation, threat mitigation table
5. **Authentication Methods** - OAuth 2.0, API keys, certificates, OpenID Connect
6. **Authentication Patterns** - 8 defined patterns for different scenarios
7. **Security Design Principles** - Security first, secure by design, common patterns
8. **Token Security** - Protection in transit and storage, token threats
9. **API Gateway Role** - Security enforcement point, threat protection
10. **Privacy and Security Assessments** - At each development stage
### Notes for Drafting
- OAuth 2.0 is the industry standard and foundation for API security frameworks
- TLS 1.3+ is mandatory with specific requirements for certificate validation
- Common security framework recommended across all APIs
- 8 authentication patterns defined with specific recommendations per pattern
- Comprehensive threat mitigation guidance with OWASP references
- Strong emphasis on "security by design" and "security first" principles
- Every API will have security component (auth, authorization, threat protection, QoS)
- Link to OWASP guidelines for secure coding and threat mitigation