These are the technical standards at my org,









Technical Standard ID

	

TTS.L1.API





Technical Standard Subject	Application Programming Interface
Version No	4.0


Document Approver Name

	

Technology Standard Board (TSB)




Document Approver Job Title

	

Technology Standard Board (TSB)




Document Owner Name

	

Wayong, Januar Triadi 




Document Owner Job Title

	

Global Head, Engineering


Document Contact Name	Yousuff, Habeeb Rahman 


Document Contact Job Title

	

Principal Solution Architect




Document Status

	




Approval Date

	

23 Oct 2024 




Effective Date

	

23 Jan 2025 




Last Review Date

	

2 May 2024 




Next Review Date

	

23 Oct 2025 










Name

	

Changes made

	

Materiality

	

Approved by

	

Version number

	

Date


Technical Standard - Application Programming Interface	

TSQF.NEW.011-Technical Standard - Application Programming Interface

	Creation	Technology Standards Council (TSC)	1.0	18 Feb 2022
Technical Standard - Application Programming Interface	

SCR.CH.013--Technical Standard - Application Programming Interface

Section 1 - Standard Ref Number link corrected
Section 2.5 - Roles section updated with library ref links
Moved 3.1.7 (Governance), 3.1.8 (Life cycle), 3.4.1 (SDF Test standards), 3.5 (Process section) to Annexes
	Modification	Technology Standards Council (TSC)	2.0	3 June 2022


Technical Standard - Application Programming Interface


	

There was a review drafted in Oct 2023 presented at TSB (10 Oct 2023), where some members recommended to relook at the scope of API and re-designate to new owner (Januar). The new changes are then incorporated in the review request below. Subsequent offline discussions resulted in change of owner and updates to the technical standard. The revised draft is presented at TSB (26 Mar 2024), which needs to address some feedback. Offline approval was subsequently provided.

SCR.CH.025--Technical Standard-Application Programming Interface

Major change : This new API standards document approaches the standard from developers' perspective encompassing key areas such as API Styles, Lifecycle Management of API and API Security Standard based on threat modelling. Post review and approval, the standards in this document will supersede existing API technical standards.  

	

Material

	

Technology Standard Board (TSB)

TSB MoM

	

3.0

	

19 April 2024


Technical Standard - Application Programming Interface	

SCR.CH.026 - Technical Standard: Application Programming Interface

Section 2.3 API Design Guidelines: Added standard statement "API.TStd.21"
Annexes, B. Reference: Added reference to "API Design Guidelines"
Section 3.11.7.1 API Registry Guidelines: Fixed typographic error from "ECM (Enterprise Domain Capability Mode) Mapping" to "Enterprise Capability Model (ECM)"
Section 3.2.1 URI Format: Fixed typographic error from "Enterprise Domain Capability" to "Enterprise Capability Model (ECM)"
Section 2.2 API Glossary: Added term definition for "SCB Cloud" and "Internet-Facing"
Section 3.1.1 Definition: Updated definition of "API Consumer Pattern", "Client Registration Required", and "Description" for better clarity and understanding
	Modification	

Technology Standard Board (TSB)

TSB MoM

	4.0	23 October 2024










1. Scope and Purpose
1.1 Purpose

Group Information Technology (IT) Standards and Group Information and Cyber Security (ICS) Standards define technical and process control objectives and requirements. Technical Standards identify technical control requirements applicable to Technology Services and set control implementation standard.

The aim of this technical standard is to comprehensively document guidelines from an engineer's perspective, covering key areas such as API design, Lifecycle management, API Styles, Error Handling, and API security standards including authentication, authorization, JWT Token format, claims usage, supported OAuth Grant flows, data protection, documentation standards and more. 

This standard also outlines requirements for API registry implementation.

API Owner/Developers and API Platform/Infra Owner must refer this standard to ensure that both existing and newly developed APIs confirm to these guidelines.

All the Guidelines documented here should be automated as much as possible using Policy as code. 




This Technical Standard defines implementation standard for the following control requirements:

Standard Ref Number	Standard Name	Version	Standard Statement Index	Standard Statement
STD00140	Solution Analysis and Design Standard	3.0	SD.SAD.SC.OC01	

Solution Architecture and Solution Design of IT Solutions are developed and agreed and cover requirements for

security,
resilience,
stability, and
business viability.

STD00158	Event Management Standard	3.0	TMT.EM.EM.OC01	

All systems / infrastructure components that are monitored adhere to a set of approved standards that are reviewed periodically by relevant stakeholders.


STD00158	Event Management Standard	3.0	TMT.EM.ED.CR01	Event Analyst must ensure that the configured alerts 
(TMT.EM.NORM01) capture the required metrics, logs, traces, or any 
other data required about the systems or application, infrastructure 
being monitored to generate meaningful data
STD00158	Event Management Standard	3.0	TMT.EM.ED.CR02	Event Analyst must ensure that the configured alerts 
(TMT.EM.NORM01) are descriptive, meaningful, and actionable so 
as to facilitate alert handling and effective decision making for Event 
Analysts or automated workflows as appropriate
STD00157	Configuration Management	3.0	RES.SAC.CI.OC01	Configuration Items used by the bank must be Identified and with their relationships maintained in a single repository. All configuration items within IT systems and infrastructure are accurately identified and cataloged.
STD00157	Configuration Management Standard	3.0	RES.SAC.CC.OC01	Configuration Reporting requirements are established, and expectation is fulfilled according to agreement with stakeholders. 
STD00155	Capacity Management Standard	3.0	RES.CAP.CP.CR01	Technology Service Owners must ensure capacity plans are 
defined and approved as per 'RES.CAP.NORM03 Capacity 
Plan', are in place for all the Technology Services they own' 
STD00155	Capacity Management Standard	3.0	RES.CAP.CP.CR02	Technology Service Owners must ensure capacity plans are 
reviewed regularly as per 'RES.CAP.NORM03 Capacity Plan', 
for all the Technology Services they own'
STD00126	IT Resilience Management Standard	4.0	RES.RM.RA.CR01	Chief Architect must develop technical standards for the Design for Availability and Resilience of Technology Services as per '2.3.1 RES.RM.NORM01 Resilience Architecture
STD00050	ICS Payment Card Data Management Standard	3.0	

PCD-090










	Mask PAN when displayed (the first six and last four digits are the maximum number of digits 
to be displayed), such that only personnel with a legitimate business need can see more than 
the first six/last four digits of the PAN. 
STD00050	ICS Payment Card Data Management Standard	3.0	PCD-110	Render PAN unreadable anywhere it is stored by use of approved hashing and encryption methods.
[Reference: ICS Standard Cryptography] 
STD00050	ICS Payment Card Data Management Standard	3.0	PCD-130	Ensure that Payment Card Data is protected during transmission over open and public.
networks using approved encryption methods.
[Reference: ICS Standard Information Handling]
[Reference: ICS Standard Cryptography]





1.2 Scope
1.2.1 Includes

The Standard only applies to APIs developed by SCB and not COTS, also it does not apply to SCB application consuming external APIs.

1.2.2 Excludes

API Gateway Standards, Testing Standards out of scope.

The ownership and organization of the infrastructure components are out of scope. 

API Monetization out of scope.

2. Definitions
2.1 Prescriptive Guidance

This document offers prescriptive guidance labeled as follows. They keyword in the below table used in the document are to be interpreted as described in [RFC2119]

Keyword	Meaning

	

Mandatory

Indicates an absolute requirement.
Failure to comply constitutes non-compliance with the specification.


	

Recommended

Indicates Strong recommendation, while not strictly required for compliance.
There may be valid reasons to deviate, and the decision should be carefully considered.




	

Optional

Indicates optional. Implementers choice to include or exclude the specified item. 


	

Prohibited

Indicates an absolute prohibition.
Failure to comply constitutes non-compliance with the specification.


	Not Recommended 
Indicates something is not recommended.
There may be valid reasons to deviate, and the decision should be carefully considered.
2.2 API Glossary

Term

	

Definition




API

	

Application Programming Interface


HTTP 	Hyper-Text Transfer Protocol
IAG	Internal API Gateway ecosystem
EAG	External API Gateway ecosystem
OAG	Outbound API Gateway ecosystem
DMZ	Demilitarized Zone
BPEC	

Business Product Extranet Channel


PSDC	

Public Service Distribution Channel


PSAC	

Product Services and Acquisition Channel


KPI	Key performance indicator
RPM	Requests per minute indicates number of requests in a specific interval
EPM	Error per minute indicates the error rate
JWT	JSON Web Token
OAS	Open API Specification
HATEOAS 	Hypermedia as the Engine of Application State
JSON	JavaScript Object Notation
OWASP	Open Web Application Security Project
CDN	Content Delivery Network
DDoS	Distributed Denial of Service
MTLS	Mutual Transport Layer Security
OIDC	OpenID Connect
OAUTH	Open Authorization
WAF	

Web Application Firewall


FAP	Functional Access Privileges
DAP	Data Access Privileges
TLS	Transport Layer Security
SSL	Secured Socket Layer
CA	Certificate Authority
SHA2	Secure Hash Algorithm 2
PEN	Penetration Test
CSP	Cloud Service Provider
IDP	Identity Provider
FQDN	Fully Qualified Domain Name
VPN	Virtual Private Network
SaaS	

Software as a Service

Examples:

Salesforce
Adobe Experience Manager
Microsoft Dynamics 365

Kebab Case	

Kebab Case is also known as spinal case or dash case, is convention for naming identifier in which multiple words are separated by hyphens ("-") commonly used in URL Paths for easy readability and interpretability by both humans and machines. In Kebab case each word is typically converted to lowercase, and hyphens are used to separate words instead of spaces or underscores.


SCB Cloud	

SCB approved and managed cloud service providers (e.g., AWS, Azure).


Internet-Facing	An internet-facing application is a software application that is accessible over the internet.
2.3 Roles & Responsibilities

Application Owner (i.e., API Developer)

API Owner is responsible for designing, developing and implementing APIs according to the established standards and best practices. 

API Owner should ensure the APIs comply with Banks standards, Industry regulations and security requirements.

API Owner is responsible to oversee the entire lifecycle of the APIs, from initial design to retirement, including versioning, documentation and deprecation strategies.

API Owner should monitor API performance and usage metrics, identify bottlenecks or issues and optimize API performance as needed.

API Owner should provide support to API consumers, maintain up-to-date documentation and communicate changes or updates effectively. 

Platform/Infrastructure Owner

The Platform/infrastructure Owner is responsible for provisioning, configuring and maintain the underlying infrastructure and platforms that support API operations.

Platform/infrastructure Owner must ensure the infrastructure is reliable, scalable and capable of handling the expected workload and traffic patterns associated with API usage.

Platform/Infrastructure Owner must implement security measures such as access controls, encryption and compliance frameworks to protect API data and infrastructure.

Platform/Infrastructure Owner must monitor infrastructure health, performance, and security metrics, respond to incidents or outages promptly.

Platform/Infrastructure Owner must conduct capacity planning to anticipate future resource requirements and scale infrastructure components accordingly to meet the growing API demands.

Platform/Infrastructure Owner must establish backup and disaster recovery procedures to ensure data integrity, availability and resilience in the event of failures or disasters.

3. Technical Standard Statements
3.1 API Classification/Patterns
3.1.1 Definition
Incoming Index	Technical Standard Statement	Technical Standard Index


RES.SAC.CI.OC01

	




#

	

API Consumer Pattern

	

API Consumer

	

API Provider

	

Client Type

	

Connectivity

	

Client Registration Required (API Registry)

	

Description




1

	

Open APIs

	

External

	

Internal

	

System

	
Internet
	

	
External APIs viewable through Internet facing developer portal
Discovered through API Registry with registration
Open Banking APIs
SCB APIs Published for Fintech Consumption
Account Aggregators







2

	

Partner APIs

	

External

	

Internal

	

System

	
Internet
Virtual Private Network (VPN)
	

	

External APIs consumed by SCB Partners and Regulators only

SCB Partners

CCIB Corporate Clients
CPBB Partnerships with Google Pay
India Bill Desk
VCAS
Visa etc.
External SaaS application (Ex: Sucess Factors) hosted on non-SCB cloud accessing on-prem application (Ex: FileNet))

Regulators

Bahrain e-Cheque APIs
Nepal Fast Payments
Nigeria Regulator APIs etc.







3

	

External Experience APIs

	

External

	

Internal

	

Human (Ex: Customer)

	
Internet
	

	

External APIs published by SCB applications which are accessible by user agents (such as, browser, mobile app) over internet.

Internet-facing SCB applications

SC Mobile
I-Banking





4	Internal Experience APIs	Internal	Internal	Human (Ex: Staff)	
Private Network
		

Internal APIs published by SCB applications which are accessible by user agents (such as, browser, mobile app) over private network.

Service Bench API consumed by Service Bench Frontend UI.
CEMS Backend API consumed by CEMS Frontend UI.
eOPS Bankend API consumed by eOPS Frontend UI.







5

	

Internal APIs

	

Internal

	

Internal

	

System

	
Private Network
	

	

Internal APIs published by SCB applications consumed by SCB applications over private network.

Communication across LOB's
Communication Within LOB 
I-Banking accessing Core Banking APIs 
I-Banking accessing Credit Card APIs







6

	

Internal APIs (SCB Cloud → On-Premise)

	

Internal

	

Internal

	

System

	
Private Network
	

	

Internal APIs published by SCB applications on-premise consumed by SCB applications on cloud over private network.

Wealth Domain Application (Apollo SCOT) hosted on cloud accessing Core Banking APIs on-premise over private network. 





7	

SaaS Inbound APIs (SaaS → SCB)

	External	Internal	System	
Internet
		

External APIs published by SCB applications consumed by SaaS applications over internet.

Dynamics 365 accessing MSL (Martech Service Layer) APIs over Internet  







8

	

SaaS Outbound APIs (SCB → SaaS)

	

Internal

	

External

	

System

	
Internet
	

	

External APIs published by SaaS applications consumed by SCB applications over internet.

Data Platform on-prem Offers service invoking RTIM SaaS service API





9	Private APIs	Internal	Internal	System	
Private Network
		

Inter-Microservice communication.

Inter API communication within the I-Banking microservices.







	API.TStd.10




3.2 API Design Guidelines
Incoming Index	Technical Standard Statement	Technical Standard Index


SD.SAD.SC.OC01










	
3.2.1 URI Format

Role: Application Owner/API Developer




API URI Format  adhere to below guidelines.




Aspect	Guidelines
Naming Conventions	

API endpoint naming  follow the kebab Case.

URIs  start with a letter.

 ensure proper casing when returning a URL in an HTTP response header value or inside a JSON response body


URI Length	

 return 414-URI Too Long if a URL exceeds 2083 characters


Character Restrictions	

 restrict the characters in the resource-collection, sub-resource-collection path segments to 0-9 a-z - with : allowed only as described below to designate an action operation.

 restrict the characters allowed in user-specified path segments (i.e. path parameters values) to 0-9 a-z - . _ ~


Relationships	

 Use forward slash (/) to indicate hierarchical relationships


Scheme	

 use https scheme for URI for Open APIs, Partner APIs, Experience APIs, Internal APIs (Across Applications)

 Use http scheme for inter-service communication with-in the application allowed only based on risk with threat modelling.

 Use http scheme for internal APIs for gRPC API style allowed only based on risk with threat modelling.


ECM Alignment	

Domain/Process API resource/sub-resource name  align with Enterprise Capability Model (ECM)


Verbs Usage	

 Use Verbs in the resource or sub-resource name







<Scheme>://<Domain>/<Version>/<Namespace>/<Primary-Resource-Collection>:<Action>/{Resource-Id}

<Scheme>://<Domain>/<Version>/<Namespace>/<Primary-Resource-Collection>/{Resource-Id}/<Sub-Resource-Collection>/{Sub-Resource-Id}

<Scheme>://<Domain>/<Version>/<Namespace>/<Primary-Resource-Collection>/{Resource-Id}? <Query-Params>




https://customer.api.sc.net/v1/client/clm/profile/identity-master:application/{channel-ref-no}

https://customer.api.sc.net/v1/client/clm/profile/identity-master:application/{channel-ref-no}/documents/{doc-id}




API Standards URI Format Conventions is limited to Scheme, Domain and Version.

Namespace, resource-collection, sub-resource-collection and query params are out of scope.




Field	Description	Example
Domain	Endpoint Domain	

customer.api.sc.net

payments.api.sc.net


Version	Major Version	

https://customer.api.sc.net/v1/clm/profile/identity-master

https://customer.api.sc.net/v1/clm/profile/identity-master:application/{channel-ref-no}/documents





Namespace	Hierarchal Path of the resource	https://customer.api.sc.net/v1/clm/profile/identity-master
Resource-Collection	Name of the primary resource	

https://customer.api.sc.net/v1/clm/profile/identity-master


Action	Action to execute on the resource	https://customer.api.sc.net/v1/clm/profile/identity-master:application
Resource-Id	Unique Identifier associated with the Primary Resource	

https://customer.api.sc.net/v1/clm/profile/identity-master:application/{channel-ref-no}


Sub-Resource-Collection	Name of the child resource	https://customer.api.sc.net/v1/clm/profile/identity-master:application/{channel-ref-no}/documents
Sub-Resource-Id	Unique Identifier associated with the Sub-Resource	https://customer.api.sc.net/v1/clm/profile/identity-master:application/{channel-ref-no}/documents/{doc-id}







	API.TStd.20
SD.SAD.SC.OC01	
3.2.2 API Design
Role: Application Owner/API Developer


Internal APIs  adhere to the "API Design Guidelines" to ensure composability and reusability.

See API Design Guidelines







	API.TStd.21
3.3 Performing an Action
Incoming Index	Technical Standard Statement	Technical Standard Index


SD.SAD.SC.OC01




	




Role: Application Owner/API Developer


REST specification is employed for representing the state of a resource and is primarily designed for managing CRUD operations.

However, there are scenarios that requires to execute an action on a resource. For instance, performing a DE Dupe action on customer resource. 

In such cases the API URL  follow the below guidelines to define the action

 use a verb as the <action> component of the path.

 use an action operation when the operation behavior could reasonably be defined as one of the standard REST Create, Read, Update, Delete, or List operations.




https://.../<<Domain>/<Version>/<resource-collection>/{resource-id}:<Action>?<Query parameters>

https://.../<<Domain>/<Version>/<resource-collection>/{resource-id}/<Sub-Resource-Collection>/{Sub-Resource-Id}:<Action>




https://...//client/clm/profile/identity-master:application/{channel-ref-no}:apply




To avoid potential collision of actions and resource ids, you  disallow the use of the ":" character in resource ids.







	API.TStd.30
3.4 Query Parameters
Incoming Index	Technical Standard Statement	Technical Standard Index
SD.SAD.SC.OC01	
API Query Parameter  adhere to below guidelines.




Role: Application Owner/API Developer








Aspect	Guideline
Consistent Naming	
API Server  use consistent and meaningful names for query parameters.

Clarity and Descriptiveness	
Query Parameters  be named and documented in a clear and descriptive manner.

Validation	
API Server  validate query parameters for correctness and completeness.

Default Values	
API Server  define default values for query parameters to enhance flexibility.

Allow Only Necessary Parameters	
API Server  avoid unnecessary query parameters for an endpoint.

Immutable Parameters	

Query Parameters that affect the identity or state of a resource  be immutable.

Clients  attempt to modify immutable parameters.

Examples

Immutable Aspect	Details
Pagination Parameters	

Query Parameters used for pagination, such as page and limit can affect the subset of data returned by an endpoint.

These parameters should be immutable to maintain consistency in pagination results.

Modifying pagination parameters mid-request could lead to unexpected or inconsistent pagination behavior.

/api/product?page=1&limit=10


Sorting Parameters	

Query Parameters used for sorting resources based on certain attributes, such as sort or order, can affect the order in which data is returned by an API endpoint.

/api/products?sort=name&order=asc


Filtering Parameters	

Query Parameters used for filtering resources based on specific criteria such as filter, search or category, may affect the subset of data returned by an API endpoint.

/api/products?category=type1


Data Range Parameters	

Query Parameters used for specifying a date range, such as start_date and end_date can affect the subset of data returned by an API endpoint within the timeframe.

/api/statements?start_date=2022-01-01&end_data=2022-12-31




Immutable Parameters for Stable Cursor Navigation

Ensure consistent cursor navigation by utilizing immutable parameters like cache key identifiers appended to API URLs.

These identifiers provide immutable references to cached datasets, ensuring data stability amid client interactions.

If HATEOAS, additionally expose links, such as "prev" and "next" to Facilite sequential navigation through the dataset.

GET /products?cache_key=abc123
{
  "products" : [..],
  "_links" {
     "prev": "/products?cache_key=abc123&page=1",
     "next": "/products?cache_key=abc123&page=3"
  }
}








Encoding and Escaping	

Special Charaters in Query parameters  be properly encoded and escaped.

Clients  encode values in accordance with URL encoding standards.


Case Sensitivity	

API Server  specify whether query parameters are case-sensitive or case-insensitive.


Deprecation	

Deprecated query parameters  be clearly documented.


Pagination	
Endpoints that support paginations, API Server  define consistent query parameters for pagination (e.g., 'page','limit')

No Behavior	

Query strings  be used for defining behavior of your API.

Example

/products?deleteALL=true

Refer Performing an Action on how to define behavior.

HTTP Methods Usage	

 Use query strings only in GET requests for filtering the values from an individual resource


Resource Identification	
 use query strings in GET requests for resource identification purposes.

Input Validation and Data Sanitization	 Sanitize Query Parameters by Stripping or Escaping potentially harmful characters to prevent Injection Attacks, such as SQL Injection or Cross-Site Scripting (XSS).
Sensitive Data Handling	

Sensitive Data in Query Parameters  be sent in encrypted form for internet facing traffic.

Sensitive Data in Query Parameters  be sent in encrypted form for internal traffic or

Sensitive Data in Query Parameters  be sent in tokenized form for internal traffic based on API provider and consumer capabilities to support tokenization based on CaaS.

Refer Data Security for more details.













	API.TStd.40




3.5 Verbs
Incoming Index	Technical Standard Statement	Technical Standard Index
SD.SAD.SC.OC01	
API Owner/Developer  adhere to below Verb usage guidelines.




Role: Application Owner/API Developer





The API  support different operations on the same endpoint/resource.

 Use HTTP Verbs on the same API endpoint to perform different operations rather than providing different API for each operation type.

 Avoid single-endpoint APIs.  overload multiple operations onto the same endpoint with the same HTTP verb.

 improve the API readability, looking at the endpoint URL and HTTP verb should tell what's its purpose without the need to see a query string.

Endpoint URLs  advertise resources and avoid verbs.

Action verbs  largely be restricted to GET, POST, PUT, PATCH and DELETE.

 be enforced at the earliest in the process chain.




Http Method	Purpose	Guideline
GET	Read	
API Servers  use 'GET' for safe and idempotent retrieval of a resource.

POST	Create	
API Servers  use 'POST' to create new resource.

PUT	Update	

API servers  use 'PUT' to update a resource.

Client  include a full representation of the resource in the request payload.

 use 'PUT', for state-changing operations.


PATCH	Partial Update	

API Servers  use 'PATCH' for a partial update to a resource.

Clients  include only the fields to be updated in the request payload.

 use 'PUT', for state-changing operations.


DELETE	Delete	

API Servers  use 'DELETE' to remove a resource.

Clients  exercise caution and confirm intentions before triggering a 'DELETE' request.


OPTIONS	Discovery	

API Servers  support 'OPTIONS' to provide information about the communication options available for a resource.

Clients  use 'OPTIONS' to discover allowed methods and other capabilities.


HEAD	Metadata	

API Servers  support 'HEAD' to provide metadata about a resource without transferring the representation.

Clients  use 'HEAD' to retrieve metadata without the full response payload.

Refer section Idempotency for Safe and Idempotent Operations.










	API.TStd.50
3.6 API Policy & PEP
Incoming Index	Technical Standard Statement	Technical Standard Index








	




Role: Application Owner/API Developer and/or Platform/Infrastructure Owner





API policy controls  be enforced using a PEP Component.

Edge
Firewall
Gateway
Ingress Controller
Application etc.

PEP component  enforce the below common policies.

API Token Generation
API Token Validation
API Token Introspection
API JWT Validation
JWT Re-Signing
Authorization (FAP, DAP)
API Spec / Schema validation
Distributed Rate Limiting
HTTP Header injection
HTTP Header Response Stripping (Ex: Server header etc)
API Traffic Logging
Request Size limiting.
Malware Protection for APIs sending binary files into the Bank.
Payload Inspection, Classification, Tokenization/Encryption etc.
API Threat Protection

API access at functional level and data level  be vetted at API Provider level (FAP / DAP checks) 










	API.TStd.60
3.7 JSON
Incoming Index	Technical Standard Statement	Technical Standard Index
SD.SAD.SC.OC01	




Role: Application Owner/API Developer








Aspect	Guideline
Confirm to JSON Specification	
APIs  confirm to the JSON specification (RFC 8529), ensuring valid JSON syntax and data structures.
Other representation like XML, HTML, TEXT  be allowed on exceptional basis due to legacy or COTS application dependency.
 use gRPC for Internal APIs. Refer API Styles on when to use gRPC

UTF-8 Encoding	

JSON Payloads  use UTF-8 encoding to ensure compatibility and consistency across different systems.


Valid JSON Object Structure	
JSON Objects  have valid structure with key-value pairs, ensuring adherence to the JSON format.

Proper Array usage	
Arrays in JSON  be used appropriately, following standards for ordered list of values.

Data Types and Values	
JSON data types and values  align with the specifications, ensuring accurate representation of data.

Use of Null values	
When representing absence of data, NULL values  be used to maintain a clear and structured format.

Large Number Handling	
JSON Implementation  properly handle large numbers to prevent loss of precision or unexpected behavior.

Escape Special Characters	
Special Characters in strings  be properly escaped according to JSON specifications to avoid parsing errors.

Consistent Naming Conventions	

Maintain consistent naming conventions for keys within JSON objects, promoting clarity and ease of understanding.

  use CamelCase keys Grammar.


Responses as JSON	

JSON message structure  be the default response for all REST API request/response, other representations can only be considered on exceptional basis.

 create responses as a JSON object and not an array as it can limit the ability to include additional metadata about results. 










	API.TStd.70
3.8 Links
Incoming Index	Technical Standard Statement	Technical Standard Index

	




Role: Application Owner/API Developer


HATEOAS or Hypermedia as the Engine of the Application state, is an architectural constraint in RESTful APIs that enable clients to navigate through the application entirely through hypermedia provided dynamically by APi providers.

API Providers  provide hypermedia links in API responses to represent available actions or transitions.

API clients/Consumers  follow hypermedia links to discover and navigate the API.

if API providers implementing hypermedia links  use well-define link relation types to indicate the semantics of hypermedia links.

If using Hypermedia API Server  include hypermedia links in error response to guide clients on possible corrective actions.

Hypermedia links  be returned for GET if further actions are needed. This also enables API Owners to update other URI’s other than the initial entry points.







	API.TStd.80
3.9 HTTP Headers
Incoming Index	Technical Standard Statement	Technical Standard Index
SD.SAD.SC.OC01	
The purpose of HTTP headers is to provide metadata information about the body or the sender of the message in a uniform, standardized, and isolated way. HTTP header names are NOT case sensitive.
3.9.1 HTTP Headers Principles
Role: Application Owner/API Developer





HTTP headers  only be used for the purpose of handling cross-cutting concerns.

Examples

Cross-Cutting Concern

	

Header Examples

	

Details




Security

	

Cross-Origin Resource Sharing (CORS)

	

Refer CORS (Cross-Origin Resource Sharing) Policy for more details.




Content Security Policy (CSP)

	







Refer section HTTP Standard Headers for more details.
















HTTP Strict Transport Security (HSTS)




Authorization




Caching and Performance

	

Cache-Control




Expires




Compression and Content Negotiation

	

Content-Encoding




Accept-Encoding




Localization and Internationalization

	

Content-Language




Content-Type




Monitoring and Logging

	

User-Agent




traceparent

	

Refer Logging & Monitoring for more details.




tracestate

API implementations  introduce or depend on headers.

Headers  include API or domain specific values.

If available, HTTP standard headers  be used instead of creating a custom header.

Service Consumers and Service Providers  expect that a particular HTTP header is available. It is possible that an intermediary component in call chain can drop an HTTP header. This is the reason business logic  be based on HTTP headers.

Service Consumers and Service Providers  assume the value of a header has not been changed as part of HTTP message transmission.







	API.TStd.90
SD.SAD.SC.OC01	
3.9.2 HTTP Standard Headers
Role: Application Owner/API Developer





Http Header Name	Applies to	Description
Accept	Request	

This request header specifies the media types that the API client is capable of handling in the response.

Systems issuing the HTTP request  send this header.

Systems handling the request  assume it is available.


Accept-Charset	Request	

This request header specifies what character sets the API client is capable of handling in the response.

The value of Accept-Charset  include utf-8.


Accept-Encoding	Request	

This request header sent by the client inform the server about its preferred content encoding.

The server can then compress the response accordingly, if supported, before sending it back to the client.

API Server  check for this header if supported  send response as compressed. 

Accept-Encoding: gzip, deflate





Authorization	Request	

Allows the client to authenticate itself with the server by including credentials in the HTTP request.

These credentials  be verified by the PEP component and API server.

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

APIs  use Basic Authentication.


Content-Encoding	Response	

This specifies the encoding applied to the payload of the message body. Typically used to compress the response body before transmitting it over the network, reducing bandwidth usage and improving transfer speed.

Content-Encoding: gzip





Content-Language	
	

This request/response header is used to specify the language of the content.

The default locale  be en-US.

API clients  identify the language of the data using Content-Language header.

APIs  provide this header in the response. 

Content-Language: en-US





Content-Type	Both	

This request/response header indicates the media type of the request or response body. 

API client  include with request if the request contains a body, e.g. it is a POST, PUT, or PATCH request.
API developer  include it with response if a response body is included (not used with 204 responses).
If the content is a text-based type, such as JSON, the Content-Type  include a character-set parameter. The character-set  be UTF-8.
Media Type	Applicability	Guideline
application/json	Request & Response	
 use as default media type

application/xml	Request & Response	

 be allowed on exceptional basis due to legacy or COTS application dependency.

 apply data sanitization, otherwise can introduce XML injection vulnerabilities.  


application/pdf	Response	
 use for PDF documents.

application/zip	Response	
 use when the content is a Zip archive.

application/gzip	Response	
 use to apply compression to reduce the payload size before sending to the client.

multipart/form-data	Request	
 use for file uploads.

image/jpeg	Request & Response	
 use to represent JPEG Image files.

image/png	Request & Response	
 use to represent PNG Image files.

image/gif	Request & Response	
 use to represent GIF Image files.

text/html	Request & Response	
 use as HTML can introduce XSS vulnerabilities.

application/javascript	Request & Response	
 use as JavaScript can introduce XSS vulnerabilities.

application/octet-stream	Request & Response	
 use as Binary data can't be identified and may contain harmful payloads.

application/x-www-form-urlencoded	Request	
 use as form-urlencoded lacks structure and can introduce injection vulnerabilities if not properly sanitized.




Accept: application/json
Accept-Charset: utf-8
Content-Type: application/json; charset=utf-8

Refer RFC 6838 for more details.


Strict-Transport-Security (HSTS)	Response	

In case of Browser based clients  Instructs the browser to communicate only over HTTPS, preventing downgrade attacks.

Strict-Transport-Security: max-age=63072000; includeSubDomains; preload




Read carefully how this header works before using it. If the HSTS header is misconfigured or if there is a problem with the SSL/TLS certificate being used, legitimate users might be unable to access the website. For example, if the HSTS header is set to a very long duration and the SSL/TLS certificate expires or is revoked, legitimate users might be unable to access the website until the HSTS header duration has expired.




Please checkout HTTP Strict Transport Security Cheat Sheet for more information.


Content-Security-Policy (CSP)	Response	

Defines a policy for controlling the origin of content that is allowed to be loaded on a website or in a web application, which helps to detect and mitigate attacks like Cross-Site Scripting (XSS) and data Injection attacks.

 include the below Directives based on the requirement.




Directive	Description	Example
default-src 	Specifies the default source for content types not explicitly defined by other directives. 	Content-Security-Policy: default-src 'self' https://trusted-domain.com; 
script-src 	Defines the allowed sources for Javascript code.	

Content-Security-Policy: script-src 'self' https://cdn.example.com;

 
style-src 	Defines the allowed sources for CSS Stylesheet	Content-Security-Policy: style-src 'self' https://styles.example.com;
image-src 	Specifies the allowed sources for Images.	Content-Security-Policy: img-src 'self' https://images.example.com;
font-src 	Specifies the allowed sources for fonts.	Content-Security-Policy: font-src 'self' https://fonts.example.com;
connect-src 	Defines the allowed sources for network connections, such as AJAX, Websocket and EventSource.	Content-Security-Policy: connect-src 'self' https://api.example.com;
media-src 	Specifies the allowed sources for media elements, such as audio and video	Content-Security-Policy: media-src 'self' https://media.example.com;
form-action 	Defines the allowed endpoints for form submissions.	Content-Security-Policy: form-action 'self' https://form.example.com;
block-all-mixed-content 	Prevents loading any insecure resources (HTTP) on a secure (HTTPS) request.	Content-Security-Policy: block-all-mixed-content;
upgrade-insecure-requests 	Automatically upgrades insecure (HTTP) requests to secure (HTTPS) requests	Content-Security-Policy: upgrade-insecure-requests;

Content Security Policy is complex to configure and maintain. For an explanation on customization options, please read Content Security Policy Cheat Sheet




This header is relevant to be applied in pages which can load and interpret scripts and code but might be meaningless in the response of a REST API that returns content that is not going to be rendered. Relevant for Type 3 (Experience) APIs





X-Content-Type-Options	Response	

In case of browser clients  include this header in HTTP response to prevent browsers from interpreting files as a different MIME type than declared.

X-Content-Type-Options: nosniff





X-Frame-Options	Response	

In case of browser clients  include this header to prevent a page from being displayed in an <frame>, <iframe>, <embed> or<object> reducing the risk of clickjacking attacks.

X-Frame-Options: DENY





X-XSS-Protection	Response	

In case of browser clients  include this header to Enable or disable the browsers built-in XSS protection filter.

Use a Content Security Policy (CSP) that disables the use of inline JavaScript.

Do not set this header or explicitly turn it off.

X-XSS-Protection: 0





Access-Control-Allow-Origin	Response	

Access-Control-Allow-Origin is a CORS (cross-origin resource sharing) header.  This header indicates whether the response it is related to can be shared with requesting code from the given origin.

 include this header in HTTP response for browser-based clients when CORS requirement.  Refer CORS (Cross-Origin Resource Sharing) Policy for more details.

Use specific origins instead of *

Access-Control-Allow-Origin: https://yoursite.com




The use of '*' might be necessary depending on your needs. For example, for a public API that should be accessible from any origin, it might be necessary to allow '*'.





User-Agent	Request	

The User-Agent Http header provides information about the client making a request to the server.

It includes details such as the type of browser, operating system, and sometimes the version. This helps server understand the capabilities and preferences of the client, allowing for customized responses. 

User-Agent: Mozilla/5/0 (Windows NT 10.0; Wind64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/97.0.4692.99 Safari/537.36





X-Forwarded-For	Request	

The X-Forwarded-For' header is a piece of information added to HTTP requests by proxies or load balancers. It contains the IP address of the client that originally made the request, helping servers identify where the request came from, especially in cases where multiple proxies are involved.

GET /index.html HTTP/1.1

Host: example.com

X-Forwarded-For: 230.0.113.195  70.41.3.18










	API.TStd.100





	
3.9.3 HTTP Custom Headers
Role: Application Owner/API Developer





Http Header Name	Applies to	Description
X-API-Version	Request	

X-API-Version  be used to indicate the minor and patch API version. Clients  include this header in their requests to access specific minor/patch version.

X-API-version: 1.0





x-deprecated	Response	

 use the x-deprecated response header to communicate clients/consumers that this API or this specific version of the API is no longer the preferred or recommended version anymore. 

The service  respond with the x-deprecated header in the following cases.

The caller has used one or more deprecated element in request.
There is one or more deprecated element in the response.

x-deprecated header  be used only for first stage of the deprecation. 




Applications consuming this header  take any action based on the value of the header at this time. Instead, the applications  take action based on the existence of the header in the response.






Sunset
	Response	

The Sunset HTTP response header field allows a server to communicate the fact that a resource is expected to become unresponsive at a specific point in time. It provides information for clients that they can use to control their usage of the resource.

The Sunset header field contains a single timestamp that advertises the point in time when the resource is expected to become unresponsive.

Sunset: Sat, 31 Dec 2023 23:59:59 GMT




Sunset header  be used only for second stage of the deprecation. 




API Deprecation happens in two stages.

First Stage: API is not the preferred or recommended version anymore.

Second Stage: The API or a specific version of the API gets decommissioned. 

Refer RFC 8594 Standard for more details.







	API.TStd.110
SD.SAD.SC.OC01	
3.9.4 Restricted HTTP Headers
Role: Application Owner/API Developer





 use 'x-market' header for market specific instance routing.

 use SNI (Server Name Indication) extension for market specific instance routing.

  include HTTP Server header in the HTTP response.

Below headers  be restricted from modifying programmatically.

Header	Type	Security Concern
Accept-Charset	Request	

Manipulating this header could impact the interpretation of the character encodings. An attacker might attempt to modify this header to force the server to response with a character encoding that suits their needs. 


Accept-Encoding	Request	Modifying this header may impact how the response content is encoded. An attacker might attempt to manipulate it to exploit vulnerabilities related to specific content encodings.
Connection	Both	Manipulating the 'Connection' header could impact the management of persistent connections. For Example, an attacker might try to manipulate it to interfere with connection handling or launch a "Connection: Keep-Alive" attack.
Content-Length	Request	Manipulating the 'Connection-Length' header may lead to misinterpretation of the message body length, potentially causing buffer overflow or other payload-related attacks.
Cookie	Request	Modifying the 'Cookie' header may impact session management and authentication. An attacker might attempt to manipulate this header to impersonate another user or exploit session-related vulnerabilities. 
Referer	Request	Manipulating the 'Referer' header could be used in attacks like Cross-Site Request Forgery (CSRF) or for privacy invasion. An attacker might attempt to control or hide the referring source.
TE	Request	Manipulating the TE header may impact how the message body is encoded or transferred. An attacker might attempt to manipulate it for payload manipulation or injection attacks.
Transfer-Encoding	Both	Manipulating the 'Transfer-Encoding' header could impact how the message body is transferred. An attacker might attempt to manipulate it to exploit vulnerabilities related to chunked transfer encoding.
Upgrade	Request	Manipulating the 'Upgrade' header could be used in protocol upgrade attacks. An attacker might attempt to manipulate it to force an upgrade to a vulnerable or malicious protocol.
Proxy-Connection	Both	Manipulating the 'Proxy-Connection' header could impact how connections are managed through proxy servers. An attacker might attempt to manipulate it for connection-related attacks.










	API.TStd.120
3.10 Http Status Codes
Incoming Index	Technical Standard Statement	Technical Standard Index

	




Role: Application Owner/API Developer


When designing REST API, don't just use 200 for success or 404 for error. Always use the semantically appropriate status code for the response.

Here is a non-exhaustive selection of security related REST API status codes. Use it to ensure you return the correct code.

Code	Message	Description
200	OK	Response to a successful REST API action. The HTTP method can be GET, POST, PUT, PATCH or DELETE.
201	Created	The request has been fulfilled and resource created. A URI for the created resource is returned in the Location header.
202	Accepted	The request has been accepted for processing, but processing is not yet complete.
301	Moved Permanently	Permanent redirection.
304	Not Modified	Caching related response that returned when the client has the same copy of the resource as the server.
307	Temporary Redirect	Temporary redirection of resource.
400	Bad Request	The request is malformed, such as message body format error.
401	Unauthorized	Wrong or no authentication ID/password provided.
403	Forbidden	It's used when the authentication succeeded but authenticated user doesn't have permission to the request resource.
404	Not Found	When a non-existent resource is requested.
405	Method Not Acceptable	The error for an unexpected HTTP method. For example, the REST API is expecting HTTP GET, but HTTP PUT is used.
406	Unacceptable	The client presented a content type in the Accept header which is not supported by the server API.
413	Payload too large	Use it to signal that the request size exceeded the given limit e.g. regarding file uploads.
415	Unsupported Media Type	The requested content type is not supported by the REST service.
429	Too Many Requests	The error is used when there may be DOS attack detected or the request is rejected due to rate limiting.
500	Internal Server Error	An unexpected condition prevented the server from fulfilling the request. Be aware that the response should not reveal internal information that helps an attacker, e.g. detailed error messages or stack traces.
501	Not Implemented	The REST service does not implement the requested operation yet.
503	Service Unavailable	The REST service is temporarily unable to process the request. Used to inform the client it should retry at a later time.







	API.TStd.130
SD.SAD.SC.OC01	
3.10.1 Status Reporting
Role: Application Owner/API Developer





Success  be reported with a status code in the 2xx range.

HTTP status codes in the 2xx range  be returned only if the complete code execution path is successful. This includes any container/SOA framework code as well as the business logic code execution of the method.

Failures  be reported in the 4xx or 5xx range. This is true for both system errors and application errors.

There  be a consistent, JSON-formatted error response in the body as per Error Schema. This schema is used to qualify the kind of error. Please refer to Error Handling Guidelines for more details.

A server returning a status code in the 4xx or 5xx range  return the response as per Error Schema in the response body.

Error Response linked to HTTP 5xx  reveal internal information, like stack traces, which can be (ab)used by malicious attacker.







	API.TStd.140
SD.SAD.SC.OC01	
3.10.2 HTTP Method to Status Code Mapping
Role: Application Owner/API Developer





 treat method names as case sensitive and should always be in uppercase.

 return the state of the resource after a PUT, PATCH, POST, or GET operation with the corresponding status based on the below table.

 return a 204-No Content without a resource/body for a DELETE operation (even if the URL identifies a resource that does not exist; do not return 404-Not Found)

 return a 200-OK from a POST Action. Include a body in the response, even if it has not properties, to allow properties to be added in the future if needed.

 return a 403-Forbidden when the user does not have access to the resource.

API developers  use only the status codes marked as  in the below table.

HTTP Method	200 Success	201 Created	202 Accepted	204 No Content	301 Not Modified	304 Not Modified	307 Temporary Redirect	400 Bad Request	401 Unauthorized	403 Forbidden	404 Not Found	422 Un processable Entity	500 Internal Server Error
GET		
	
	
									
POST				
									
PUT		
											
PATCH		
	
										
DELETE		
	
										
HEAD		
	
										
OPTIONS		
	
										




Refer RFC 7231 Standard for more details.




	API.TStd.150




3.11 API Lifecycle Management
Incoming Index	Technical Standard Statement	Technical Standard Index

	
3.11.1 API Lifecycle Stages
Stage	Description
Design	
Define the purpose, functionality, and specifications of the API.
Create API contracts and document endpoints.

Development	
Implement API based on the design specifications. Ensure API meets the requirements.

Testing	
Verify functionality, performance and security through approved testing methods, including unit testing, integration testing, and end-to-end testing.

Documentation	
Create comprehensive documentation, including details on endpoint usage, authentication, error handling, and other relevant information for developers.

Deployment	
Release API into production environment with the required configuration and security and make the API accessible.

Monitoring & Analytics	
Implement tools to monitor API performance, usage and health. Collect insights to identify issues and understand how the API is used.

Depreciation & Retirement	Plan and communicate the deprecation of the older versions or the retirement of the API. Provide migration for paths for consumers to transition newer versions or alternatives.




	API.TStd.160

	
3.11.2 Versioning
3.11.2.1 Semantic Versioning (SemVer)

Semantic versioning is a popular versioning scheme that assigns three numbers to each version: MAJOR.MINOR. PATCH.

These numbers are incremented based on the type of changes introduced.

	API.TStd.170

	
3.11.3 API Versioning Principles
Role: Application Owner/API Developer


All APIs  be versioned and  follow these Guidelines.

API Specification  follow the versioning scheme. Use the 'v' prefix for versions, with the major starting at 1 for the initial LIVE release and minor starting at 0 for the first minor release of any major version.

Every incremental change, weather backward compatible or not,  version for proof labelling, documentation, review, discussion, publication and communication.

API endpoints  only include the major version.

API specification versions signify interface changes and  differ from service implementation changes.

Minor API versions  maintain backward compatibility within the same major version.

Major API versions  choose to maintain backward compatibility with the previous major version.







	API.TStd.180

	
3.11.4 Backward Compatibility
Role: Application Owner/API Developer


APIs  adhere to the following principles to be considered backwards compatible.

APIs  be designed in a forward and extensible way to maintain compatibility and avoid duplication of resources, functionality and excessive versioning.

All changes  be additive.

All changes  be optional.

Semantics  change.

Query-parameters and request body parameters  be unordered.

Additional functionality for an existing resource  be implemented either as an optional extension, or as an operation on a new child resource, or by altering a request body, while still accepting all the previous, existing request variations, if an existing operation (e.g., resource creation)  be reasonably extended.

All services provider  only support n-2 versions.







	API.TStd.190





	
3.11.5 List of Backwards Incompatible Changes
Role: Application Owner/API Developer





A resource URI  support additional query parameters but they  be mandatory.

There  be any change in the behavior of the API for request URIs without the newly added query parameters.

A new parameter with a required constraint  be added to a request.

The semantics of an existing parameter, entire representation, or resource  be changed.

A service  recognize a previously valid value for a parameter and  throw an error when used.

There  be any change in the HTTP status codes returned by the URIs.

There  be any change in the HTTP verbs (e.g. GET, POST, PUT or PATCH) supported earlier by the URI. The URI  however support a new HTTP verb.

There  be any change in the name and type of the request or response headers of an URI. Additional headers  be added, provided they’re optional.







	API.TStd.200

	
3.11.6 API Deprecation Best Practices

Notify Consumers: Provide ample notice to API consumers before deprecating an API version. Update the API in the Documentation as depreciated. OAS provides an annotation to mark an operation as depreciated.

Migration Guide: Provide consumers with clear migration guide that explain how to transition to the new API version.

Support: Offer support to users who are having trouble migrating to the new API version.

Monitor Usage: Monitor the usage of the deprecated API version to ensure the consumers are successfully transitioned to the newer version.

Role: Application Owner/API Developer








Graceful Deprecation
Monitor Usage	 Continuously monitor the usage of the old API version to identify any remaining dependencies or active users.
Minimal Requests to old API	 Strive for minimal incoming request to the old API as the deprecation date nears. A decrease in usage indicates successful migration to the new version.
HTTP Status & Error Codes	

Once the deprecation date reached, configure all old API endpoints to return 'x-deprecated' custom HTTP header signaling the clients/consumers about the deprecation and once the retirement date reached  return the 'Sunset' header with HTTP Status 410 - Gone and appropriate error details signaling the retirement.

Refer HTTP Custom Headers for deprecation and sunset headers details.


Error Message	

 Accompany the HTTP error codes with clear and informative error message, indicating the retirement of the API version and providing guidance on transitioning to the new version.

If HATEOAS support available, then the response  include a HATEOAS link to the new API.


Discontinuation Process	 Systematically decommission the supporting infrastructure or services associated with the deprecated/retired version.
Documentation Update	 Update documentation to reflect the complete discontinuation of the old API version. Clearly communicate all consumers that the old version is no longer supported.
Post-Deprecation Support	Provided a limited post-deprecation support period, if feasible to address any critical issues that may arise after the complete discontinuation. 










	API.TStd.210

	
3.11.7 gRPC Versioning
Role: Application Owner/API Developer








Aspect	Guideline
Service Addressing and Versioning	

The package name combined with the service name  form a unique service address.

Each version of the service  be identified by a distinct package name and  include a version number.

Multiple versions of the service  be hosted side-by-side.

Example

syntax = "proto3";

//Package name includes the Major versioning information
package CLientLifeCycleManagement.Profile.v1

//Define the Customer Identity Master Service
service CustomerIdentityMaster {
	//RPC method for managing Customer Identity Master Information
	rpc application (CustomerRequest) returns (CustomerResponse);
}

//Request message for creating a CustomerIdentityMaster instance
message CustomerRequest {
	//Sample fields for customer data
	string applicationNumber =1;   string customerName =2;
}

//Response message for creating a customerIdentityMaster instance
message CustomerResponse {
 //Sample fields for customer response data
 	string applicationNumber =1;   
	string customerName =2;    
	string status =3;
}





Versioning Strategy	

 include a Major version number in the package name to indicate different service versions.

 update the Major version number unless making breaking changes to the service contract. 

Service Implementations  follow Semantic Versioning (SemVer).

 support backward compatibility with older versions of the services if MINOR and PATCH changes.

Minor and PATCH version can't be included within the Protobuf file. It  be managed outside of the Protobuf either in generated code or in documentation. 





Reducing Duplication	

 consider centralizing business logic to reduce duplication across different service versions.

Business logic  be separated from service implementations to allow for easier reuse and maintenance. 


Backward Compatibility	

Non-Breaking Changes

These changes are non-breaking at a gRPC protocol level

Adding a new service
Adding a new method to a service
Adding a field to a request message

Fields added to a request message are deserialized with the default value on server when not set.

To be a non-breaking change, the service  succeed when the new field isn't set by older clients.

Adding a field to a response message

Fields added to a response message are deserialized into the message's unknown fields collection on the client.

Adding value to Enum - Enums are serialized as a numeric value. new Enum values are deserialized on the client to the Enum value without an Enum name. To be non-breaking change, older clients

Enums are serialized as a numeric value. new Enum values are deserialized on the client to the Enum value without an Enum name.

To be non-breaking change, older clients  run correctly when receiving the new Enum value.

Protocol Breaking Changes

Renaming a field 

with Protobuf content, the field names are only used in generated code.

The field number is used to identify fields on the network.

Renaming a field isn't a protocol breaking change for Protobuf. However, if server is using JSON content, then renaming a field is a breaking change.

Changing a field data type

The field names are only used in generated code with Protobuf content.

The field number is used to identify fields on the network. Renaming a field isn't a protocol breaking change for Protobuf. However, if server is using JSON content, then renaming a field is a breaking change.

Renaming a package, service or method

gRPC uses the package name, service name, and method name to build the URL. The client gets an UNIMPLEMENTED status from server.

Removing a service or method

The client gets an UNIMPLEMENTED status from server when calling the removed method.













	API.TStd.220


RES.SAC.CI.OC01







	
3.11.8 API Registry

Ensure Internal and External APIs are easily discoverable, understandable, simple to subscribe, and easy to utilize.

An API is only good as its documentation. API should not be considered done until documentation is made available.

3.11.7.1 API Registry Guidelines

The following guidelines help the design usage of an API Registry, ensuring that it serves as a valuable and well-managed resource within the organization.

Role: Platform/Infrastructure Owner








API Registry Aspect	Guideline
Centralized Repository	

An API Registry  serve as a centralized repository for cataloging and storing information about all APIs within the organization for all LOBs (CPBB, CCIB, Functions etc.), ensuring a unified and easily accessible source. 


Traceability	Each API endpoint  be assigned a globally unique identifier within the API registry to ensure clear identification and traceability.
Version Tracking	

The API Registry  track and display version information for each API, aiding developers and consumers in understanding the evolution and compatibility of APIs.


Access Control	

Access to the API Registry  be controlled and secured, ensuring that only authorized personnel can view, modify, or contribute to the entries within the registry. Access control support for internal developers, third party and partner developers.


Search and Discovery	

The API registry  provide robust search and discovery features, enabling users to efficiently find relevant APIs based on criteria such as API Name, Business Segment (Ex: CCIB, CPBB, Functions etc.), Sub-Business Segment (Ex: Retail, Business Banking, Wealth etc.), Application name or ITAM, API Type (Open, Partnership, Internal), Market, Status (Draft, Pipeline, Ready for Production, Production), and version.

 have support for tagging to enhance discoverability. 


Metadata Management	

APIs in the registry  include comprehensive metadata describing their purpose, functionality, and usage to facilitate discovery and understanding.

API metadata  include essential information such as name, description, version, endpoints, parameters, supported operations and market information to provide comprehensive overview of capabilities.


Enterprise Capability Model (ECM)	

All Domain APIs  be tagged to ECM during API Registration, that enables API search and discovery features through ECM capabilities.




ID	Name	Domain	HTTP Method	Endpoint	ECM
1	Individual Client Details	Client	

GET

POST

PATCH

	

https://<BasePath>/v1/individuals/{client-id}

	1.2.2.1.1 Client Identity Master
2	Individual Client Address	Client	GET	https://<BasePath>/v1/individuals/{client-id}/addresses	1.2.2.1.1 Client Identity Master
3	Individual Client Contact	Client	GET	https://<BasePath>/v1/individuals/{client-id}/contacts	1.2.2.1.1 Client Identity Master
4	Individual Client Risks	Client	

GET

POST

PATCH

	https://<BasePath>/v1/individuals/{client-id}/risks	1.2.2.3.4 Client Risk Assessment
5	Individual Client Documents	Client	

GET

POST

	https://<BasePath>/v1/individuals/{client-id}/documents	1.2.2.3.6 Client Documentation
6	Individual Client Investment Profile (CIP)	Client	

GET

POST

	https://<BasePath>/v1/individuals/{client-id}/investment-profile	1.2.2.1.4 Investment profile
7	Individual Client Aliases	Client	GET	https://<BasePath>/v1/individuals/{client-id}/aliases	1.2.2.1.1 Client Identity Master
8	Individual Client Dedupe	Client	POST	

https://<BasePath>/v1/individuals:dedupe

	1.2.2.2.1 Initial Risk Assessment








Security Controls	APIs  be identified by its data classification based on sensitivity, confidentiality and regulatory requirements associated with the data they handle those aids in addressing data severity enforcement.
Lifecycle Management	

APIs in the Registry  undergo lifecycle management, reflecting their development stages from Design to Deprecation, aiding in transparency and governance.


Documentation Links	

Each API entry in the Registry  include links to comprehensive documentation, ensuring that developers have easy access to information needed for integration.


Usage Metrics	

The API Registry  include usage metrics, providing insights into the popularity and consumption patterns of APIs, aiding decision-making processes. Refer API Usage Metrics


NFR & SLA	The API Registry  include the NFR and SLA aspects of the API, which help drive the policy automation, analytics and operational activities. 
Dependency Mapping	

The Registry  support the mapping of dependencies between APIs, offering a clear understanding of how different APIs interact within the ecosystem.


Collaboration Features	

The API Registry  incorporate collaboration features, allowing developers and stakeholders to provide feedback, share insights, and contribute to the improvements of APIs.


Integration with CI/CD	

The API Registry  integrate with CI/CD pipelines, automatically updating information about APIs as they progress through the development lifecycle.


Automated Approval Workflow	

The API Registry  include an automated approval workflow, streamlining the process of adding new APIs or modifying existing entries.


Notification System	

The API Registry  feature a notification system to alert stakeholders about changes, updates, or important events related to listed APIs.

The Notification System  various events like API version updates, Workflow status changes, Security Alerts, Service Interruptions or maintenance, Policy Changes and Performance Metrics

End users  have the ability to customize their notification preferences based on their specific needs and preferences.

This  include Notification channels, Event Filters, Frequency settings etc.


Quality Ratings	

The API Registry  Include a system for quality ratings or reviews, providing insights into the user experience and effectiveness of different APIs.

The Rating  be derived from User Feedback, Performance Metrics, Documentation Quality and Support, API Standards Compliance and Community Engagement.










	API.TStd.230
3.12 API Styles
Incoming Index	Technical Standard Statement	Technical Standard Index

	




Role: Application Owner/API Developer





 use REST for Open APIs and Partnership APIs

 use GraphQL or REST for experience APIs

3.12.1 GraphQL Consideration

GraphQL  be considered when the client needs flexibility in requesting specific data fields and avoiding over-fetching or under-fetching of data.

GraphQL  be considered when real-time updates or subscriptions are required for live data interactions.

GraphQL  be used when there is a preference for a single endpoint for all data operations, simplifying client-server interactions.




 use REST and/or gRPC for Internal APIs

The use of gRPC protocol  be limited to East-West traffic.

3.12.2 gRPC Consideration

 use gRPC protocol if high-performance and low-latency requirements.

 use gRPC for inter microservice communication within the application boundary where TLS/MTLS constraints due to certificate management allowed only based on risk with threat modelling.

gRPC  used for browser-based clients.

gRPC  used when there is rigid and unchanging API contract.










	API.TStd.240

	
3.12.1 Error Handling Guidelines
Role: Application Owner/API Developer


According to HTTP specifications, the outcome of a request execution is represented by a status code and a reason phrase. Status codes in the 4xx range indicate client-side errors, while those in the 5xx range indicate server-side errors.

To provide more detailed and machine-readable information about errors, APIs must return a JSON error response.




#	Aspect	Guideline
1	JSON Error Representation	

APIs  return a JSON error representation adhering to the schema mentioned below.


2	Standard HTTP Status Codes	

 Use only Standard HTTP status codes as per the section HTTP Method to Status Code Mapping 


3	Human-Readable Reason Phrase	

 Include a human-readable reason phrase in the response for clarity on outcome of the request, helping developers and users understand the nature of the error.


4	Machine-Readable Information	

 ensure the error responses provide sufficient machine-readable information, aiding non-human consumers of the API in understanding and programmatically resolving errors.


5	Secure Error Handling	

APIs  provide secure error messages that avoid exposing sensitive information, helping to prevent data leakage and providing minimal information to potential attackers.

Error Responses  reveal internal information, like stack traces, which can be (ab)used by malicious attacker.

3.12.2 Error Schema
[
    {
        "id": "<transaction 36-char uuid>",
        "code": "<Error Code>",
        "detail": "<Error Message>",
        "source": "<Optional field to indicate exact field throwing the error>"
    },
    {
        "id": "<transaction 36-char uuid>",
        "code": "<Error Code>",
        "detail": "<Error Message>",
        "source": "<Optional field to indicate exact field throwing the error>"
    }
]
3.12.3 Standard Errors Catalog 
Error Codes	Error Messages	HTTP Code	Remarks
Generic issues	
	
	

E001	Field is mandatory	400	

Mandatory field is missing from the request.

source field will return the name for the invalid field. Multiple errors will be returned for multiple invalid fields.


E002	Field value not in valid range	400	

Request field length does not meet the requirements.

source field will return the name for the invalid field. Multiple errors will be returned for multiple invalid fields.



E003	Invalid Format	400	

Request fields having invalid format, eg date, amount, time.

source field will return the name for the invalid field. Multiple errors will be returned for multiple invalid fields.


E004	Contains invalid characters	400	

Request fields having invalid special characters.

source field will return the name for the invalid field. Multiple errors will be returned for multiple invalid fields.


E005	Resource not found	404	Missing resource (such as rel-id) in downstream systems.
E006	No unique resource found	400	Multiple resources (such as customers) in downstream systems.
E007	Invalid Input	400	Request field failed validation in downstream systems.
Certificates / Key related issues	
	
	

E100	Unable to decrypt	500	

E101	Unable to verify signature	500	

E102	Unable to decrypt or verify signature	500	

E103	Unable to encrypt	500	

E104	Unable to sign	500	

E105	Unable to encrypt or sign	500	

E110	Invalid MTLS Cert	400	Invalid x-mtls-cert-cn provided when this header is used to map to partners instead of subject (Mostly for MTLS based APIs)
E111	Invalid Token Error	401	Invalid / Missing / Unable to verify the token / Missing field in token
E112	Forbidden	403	ACL Unauthorized Errors
Downstream Errors	
	
	

E200	Downstream System Error	500	

source field will be "step-name"

eg.

"source": "EBBS Customers Profile API"

"source": "GNS RT API"


E201	Internal API Gateway Error	500	Internal Kong Gateway returns an error.
E202	Timeout Error	500	Downstream systems did not respond within the SLA and timed out.
Data Errors	
	
	

E300	Modify request as message is too large	413	Downstream systems returned more records than expected. ie customers products returned more than stipulated.
Others	
	
	

E999	Unexpected error occurred	500	











	API.TStd.250
3.13 Infra & Network design
Incoming Index	Technical Standard Statement	Technical Standard Index











	




Role: Platform/Infrastructure Owner


Network and infrastructure design  comply with standard offerings of the group.

API Consumers from internet and non-internet reaches SCB systems through different networking channels.

Some of the special scenarios include in-country implementation, or new data center usage, multi cloud, SaaS, corporate customers with leased line connectivity etc.,

The domain and integration architects  define the standard integration patterns.

#

	

API Consumer Pattern

	API Invocation Path


1

	

Open APIs

	
EDGE → PSDC (DMZ1+DMZ2) → GWAN



2

	

Partner APIs

	
EDGE → PSDC (DMZ1+DMZ2) → GWAN
BPEC (VPN) → PSDC (DMZ2) → GWAN



3

	

Experience APIs

	
EDGE → PSDC (DMZ1+DMZ2) → GWAN
EDGE → PSDC (DMZ1+DMZ2) → Cloud Connect Service → Cloud

Cloud Connect Service

AWS Direct Connect
Azure Express Route





4	Internal Experience APIs	
GWAN → PEP (Ex: Gateway, Ingress Controller, F5 etc) → GWAN



5

	

Internal APIs

	
GWAN → PEP (Ex: Gateway, Ingress Controller, F5 etc) → GWAN
SCB Cloud → Private Network (Ex: VPC, VNet) → SCB Cloud
SCB Cloud → Cloud Connect Service → GWAN
GWAN → Cloud Connect Service → SCB Cloud



6

	

SCB Cloud → On-Premise

	
SCB Cloud → EDGE → PSDC (DMZ1+DMZ2) → GWAN
SCB Cloud → Cloud Connect Service → PSDC (DMZ1+DMZ2) → GWAN.







	API.TStd.260




3.14 API Security
Incoming Index	Technical Standard Statement	Technical Standard Index








	
3.14.1 Authentication & Authorization
3.14.1.1 Principles & Guidelines
Role: Application Owner/API Developer and/or Platform/Infrastructure Owner


Authorization is the process of granting or denying access to API endpoints or resources based on the permissions associated with the requesting entity. It involves validating the identity of the client (application or user) and determining whether the identified entity has the necessary rights to perform the requested actions on the API.

Principle/Aspect	Guideline
Least Privilege	

 Provide only the minimum level of access necessary for a user or a system to perform its job function.


Need-to-Know Basis	

Users or Systems  only have access to the information necessary to perform their duties.


Consistent Enforcement	

 ensure the authorization policies are consistently enforced across all endpoints. 


Authentication	

All APIs (Open, Partner, Experience, Internal)  Implement only the approved authentication models to ensure only authorized clients can access resources.

APIs  allow insecure or weak authentication mechanisms that could compromise the confidentially and integrity of user credentials.

 Use an authentication server that issues a token compliant with the standard SCB JWT structure.


Authorization Headers	

 use standard authorization headers (Ex: "Authorization: Bearer <token>") to transmit authorization information securely.


Authorization	

Coarse-Grained Authorization using Authorization server  be performed at the PEP level.

Fine Grained Authorization  be performed at the API server level using Authorization server solution.

Each LOB and sub-LOBs  have more than one authorization server due to authorization model complexity requirements and all Authorization servers  support a common JWT structure and standard.


Centralized Authorization Server	

 consider implementing a centralized authorization server for managing and enforcing access policies consistently.


Separation of Policy and Code	

Authorization policy  be expressed in its own textual representation independent of application language and framework. It is stored, versioned and controlled by policy admin. Policy changes can occur without redeploying the application.


Secure by Default	

Policy decisions  default to "no" (a closed system). revaluated in real-time, independent of authentication token's lifetime. Enhances security by minimizing default access and dynamically evaluating policies.


Logging and Auditing	

 Log security events for auditing purposes.

 monitor and analyze logs to detect and respond to unauthorized access attempts.


Periodic Review and Update	

 conduct regular reviews of authorization polices and update them based on changes in application, user roles or security landscape.







	API.TStd.270








	
3.14.2 Authentication Patterns
Role: Application Owner/API Developer and/or Platform/Infrastructure Owner

3.14.2.1 Open API Authentication (Internet-PSDC Channel)

Open API Clients/Consumer  choose one of the following authentication methods to authenticate in order to obtain the access token from Identity Server.

 use OAuth (MTLS Cert Thumbprint + ClientID) to authenticate with the Identity Server to obtain the access token if using a partner's platform/channel. 

MTLS is required to establish trust between SCB and third-party client platform (Ex: Account Aggregator), additionally due to service-to-service communication occurring over the internet, client secrets cannot be utilized for client credentials grant flow instead MTLS Client Thumbprint is used as a substitute for client secret. 







 use OAuth to authenticate with the Authorization Server to obtain the access token if using Banks own platform/channel.

 use signed Tokens to ensure Token Integrity.

API Gateway/PEP component  apply the API policies (Ex: Token Validity, Integrity, Authorization etc.) before grating access to the requested resource.  Refer API Policy & PEP for more details.

Open API  use only approved secure transport TLS. (For Version details Refer SCB Acceptable TLS Cipher Suites)

 apply user consent if user data shared with Third-Party Platform (TPP) [Ex: Account Aggregators, Partners aligned to PSD2]

Refer Consent and Claims for more details. 

 apply End-to-End Encryption (E2EE) for scenarios where APIs carrying sensitive data. Refer Data Security for more details.

3.14.2.2 Partner API Authentication (Internet-PSDC Channel)

Partner API Client/Consumer  choose one of the following authentication methods to authenticate in order to obtain the access token from Identity Server.

 use OAuth (client_assertion + ClientID) to authenticate with the Authorization Server to obtain the access token.

Here client_assertion is Signed PrivateKey JWT establishes the trust between SCB and third-party Partners platform (Ex: Google Pay).







 use OAuth (MTLS Cert Thumbprint + ClientID) to authenticate with the Identity Server to obtain the access token

Here MTLS establishes the trust between SCB and third-party Partners platform (Ex: Google Pay), additionally due to service-to-service communication occurring over the internet, client secrets cannot be utilized for client credentials grant flow instead MTLS Client Thumbprint is used as a substitute for client secret. 




 use signed Tokens to ensure Token Integrity.

API Gateway/PEP component  apply the API policies (Ex: Token Validity, Integrity, Authorization etc.) before grating access to the requested resource.  Refer API Policy & PEP for more details.

Partner APIs  use only approved secure transport TLS. (For Version details Refer SCB Acceptable TLS Cipher Suites)

 apply End-to-End Encryption (E2EE) for scenarios where APIs carrying sensitive data. Refer Data Security for more details.




Method 1:

POST /oauth2/token HTTP/1.1

Host: identity-server.com

client-id: your-client-id

scope: read write 

Method 2:

POST /oauth2/token HTTP/1.1

Host: identity-server.com

client-id: your-client-id

scope: read write 

uuid: your-client-uuid

SignedJWT




3.14.2.3 Partner API Authentication (Leaseline-BPEC Channel)

Partner API Client/Consumer  connect to the Private Network. 

Partner API Client/Consumer  choose one of the following authentication methods to authenticate in order to obtain the access token from the Identity Server.

 use MTLS to authenticate with the Identity Server.

MTLS is required to establish trust between SCB and Partners platform (Ex: Regulatory, VISA etc). 

 use signed Tokens to ensure Token Integrity.

API Gateway/PEP component  apply the API policies (Ex: Token Validity, Integrity, Authorization etc.) before grating access to the requested resource.  Refer API Policy & PEP for more details.

Partner APIs  use only approved secure transport TLS. (For Version details Refer SCB Acceptable TLS Cipher Suites)

3.14.2.4 Experience API Authentication (PSDC Channel)

Experience APIs  use Hybrid flow (OIDC + OAuth 2.0) for scenarios requiring both ID tokens and access tokens.

Experience APIs  use only OAuth 2.0 grant for scenarios where ID tokens are not required.

Experience APIs  use only approved secure transport TLS. (For Version details Refer SCB Acceptable TLS Cipher Suites)

 apply End-to-End Encryption (E2EE) for scenarios where APIs carrying sensitive data. Refer Data Security for more details.

 use signed Tokens to ensure Token Integrity.

API Gateway/PEP component  apply the API policies (Ex: Token Validity, Integrity, Authorization etc.) before grating access to the requested resource.  Refer API Policy & PEP for more details.

Experience APIs  use self-contained encrypted and signed tokens otherwise Opaque token when there is a usage restriction due to regulatory or market specific requirements.

 apply End-to-End Encryption (E2EE) for scenarios where APIs carrying sensitive data. Refer Data Security for more details.

3.14.2.5 Internal API Authentication 

Internal APIs used for service-to-service communication  use mTLS to authenticate with the Identity server to get the access token.

Internal APIs  use the standard JWT structure to authorize access.

MTLS is required to establish trust between Server Provider and Identity Platform. 

Internal APIs  use only approved secure transport TLS. (For Version details Refer SCB Acceptable TLS Cipher Suites)

 use signed Tokens to ensure Token Integrity.

API Gateway/PEP component  apply the API policies (Ex: Token Validity, Integrity, Authorization etc.) before grating access to the requested resource.  Refer API Policy & PEP for more details.

 use clear access tokens considering internal traffic.







	API.TStd.280
3.15 OIDC & OAuth Grant Flows
Incoming Index	Technical Standard Statement	Technical Standard Index

	




Role: Application Owner/API Developer and/or Platform/Infrastructure Owner





#	OIDC/OAuth Grant Flow + Extension	Purpose/Guideline
1	Authorization Code Grant + PKCE	

Authorization Code Grant Flow with Proof Key for Code Exchange (PKCE) is an OAuth 2.0 extension enhancing security for public clients, such as mobile or SPA (Single Page Applications). PKCE mitigates authorization code interception risks, ensuring a secure token exchange process between the authorization server and the client.

 implement authorization code grant for web and mobile application to securely obtain access tokens.

 implement proper redirection URI validation to prevent authorization code interception attacks.

 use PKCE (Proof Key for Code Exchange) to enhance security in authorization code flows to prevent the code interception attacks.

 use secure channels (HTTPS) for all communication involved in the authorization code grant. 





2	

Hybrid Flow

(OIDC + Authorization Code)

	

OpenID Connect (OIDC) Flow is a protocol that extends OAuth 2.0 to allow clients (applications) to verify the identity of end-users based on the authentication performed by an authorization server, as well as to obtain basic profile information about the end-user.

OIDC offers additionally an ID Token (User Claims and Information) and a User Info Endpoint, to retrieve additional user information after the initial authentication.

 implement hybrid flow when the client-side application requires user information for a personalized and interactive experience or display user-specific content or customize UI based on user attributes.

 use this flow for scenarios requiring both ID tokens and access tokens, providing a balance between security and efficiency.





3	Refresh Token Grant	

The Refresh Token Grant is an OAuth 2.0 flow allowing clients to obtain new access tokens without user interaction by using a refresh token. This enhances security and convenience, reduces the need for users to repeatedly authenticate.

 use refresh token grant along with "Authorization Code Grant Flow" for web and mobile applications.

 rotate refresh tokens periodically to mitigate potentials risks.





4	Client Credentials Grant	

The Client Credentials Grant Flow is an OAuth 2.0 flow where a client (server-side application), directly requests an access token from the authorization server by presenting its client credentials (Client ID and secret). The flow is suitable to machine-to-machine communication, where the client acts on its own behalf without user involvement.

 use only client credentials grant for service-to-service authentication (East-West Traffic).





5	Client Credentials Grant + DPoP	

The Client Credentials Grant Flow with DPoP (Distributed Proof of Possession) enhanced version of the Client Credentials Grant Flow. It introduces an additional layer of security by requiring the client to provide a signed DPoP proof, which demonstrates possession of a private key, along with client credentials when requesting an access token. This adds an additional layer of protection against unauthorized access and token misuse in client-server communication. 

Usage: This grant flow usage  be limited to third-party clients (Open APIs, Partner APIs) for internet-based traffic.

Authentication: Clients  authenticate using their client credentials (Client ID and secret) in communication with DPoP proof.

DPoP Proof: Clients  generate a DPoP proof, a signed JWT (JSON Web Token) to demonstrate possession of a private key associated with the client.

Token Request: Clients  include the DPoP proof in the token request as an additional parameter.

Proof-validity: DPoP proofs  have a short expiration time to limit their validity, reducing the risk of compromise.

Server Verification: Authorization servers  validate the DPOP proof, ensuring its signature and checking for expiration.

Token Issuance: Only upon a successful verification, the authorization server  issue the access token to the client.





6	On-Behalf-Of Flow (OBO)	

The "OAuth OBO" Flow is commonly referred to as the "Act on Behalf" flow in the context of OAuth 2.0. This flow allows a client application to obtain an access token to act on behalf of a resource owner (Typically a User), with the user's consent. The client application is granted permission to perform actions on the resource server on behalf of the resource owner.

User Consent: The client application  obtain explicit consent from resource owner before acting on their behalf.

The resource owner  provide clear and unambiguous consent for the client application to act on their behalf.

Access Token Issuance: Upon successful consent, the authorization server  issue an access token to the client with appropriate scope and permissions.







Domain	Scenario	Detail
CPBB-Retail	Contact Center	Contact Center Acting on-behalf of Customer. 
CCIB	RM Working on CRM	RM accessing client details in CRM.
Client Payment by Ops	Ops doing Payments on be-half of client.













	API.TStd.290
3.16 JWT Token Standards
Incoming Index	Technical Standard Statement	Technical Standard Index

	
3.16.1 Guidelines
Role: Application Owner/API Developer and/or Platform/Infrastructure Owner





#	Token Aspect	Guideline
1	Authentication	

API Clients  authenticate using banks approved OAuth 2.0 Grant flows based on the API Types (Open, Partner, Experience, Internal).


2	Authorization	

 use scopes for Coarse Grained Authorization.

 use claims for Fine Grained Authorization.


3	Token Expiration	

Access Tokens  have limited lifespan, and the 'exp' claim  be used to specify the expiration time.  

The Token Expiry time  adhere to the ICS Security Standards. Refer page Identity and Access Management section 3.3.3 "Authentication At Logon" for timeout details.


4	Token Issuer Verification	

API Service Provider  verify the 'iss' claim to ensure the tokens are issued by the relevant internal Identity server.


5	Signature Verification	

Token Signatures  be validated using the secured algorithm, and the 'alg' header  specify the bank approved cryptographic algorithm.   Refer ICS Cryptography Standard


6	Secure Transmission	

JWTs  be transmitted securely over HTTPS to prevent eavesdropping and tampering during transit.

JWTs within the inter-microservice communication  be clear.


7	Refresh Token Handling	

When Implementing Refresh Tokens, clients  securely handle the renewal process.


8	Claim Validation	

API Service Provider/PEP Component  validate standard claims such as 'sub' (Subject) and 'aud' (Audience) for proper token usage.

API Service Provider/PEP Component  validate if all the required claims are present based on scope.


9	Encryption	

Sensitive Information within the JWT payloads  be encrypted using bank approved algorithms, and 'enc' claim  specify the encryption algorithm.

 use the JWE standard for Token Encryption


10	Custom Claims Limit	

 restrict the number of custom global claims in the JWT to max of '20'.


11	Global Custom Claim Reuse	

 reuse the Global Custom Claims as much as possible, not to introduce new ones


12	Self-Contained Tokens	

 use Encrypted and Signed self-contained tokens for North-South traffic.

Use Clear Self-Contained token for East-West traffic.

 use Self-Contained tokens only for Experience APIs.


13	PEP (Point of Enforcement Policy)	

The PEP component  validate the access token if all the required claims are present based on the scope value. Refer Scopes section for more details. 

Coarse grain authorization  be based on scopes for access to the resources by the API Gateway/PEP. 

Fine grained authorization  be completed using the Authorization solution.


14	JWT Token Size Limit	

JWT Tokens are transmitted using HTTP headers.   ensure that the size of the JWT token payload remains within the acceptable limits.

It's recommended to keep the Token size within 4 Kilobytes as larger HTTP requests will likely be declined by webservers due to default max HTTP header size limits.

 Limit the use of number of custom claims.

 consider optimizing the length of the claim values, still considering clarity and readability. 







	API.TStd.300

	
3.16.2 Token Types
Role: Application Owner/API Developer





Token Type	Definition/Guideline
ID Token	

The claims in the ID Token are intended for the Client to decode and use. These are issued during an interactive flow where the user authenticates.

 use clear ID tokens when the client-side application requires user information for a personalized and interactive experience or display user-specific content or customize UI based on user attributes. 

ID Tokens  contain sensitive data (PII, PCD)





Access Token	

The claims in the Access Token are not for the Client but for the API when the Client passes the Access Token in the call to the API.

The Experience APIs  use encrypted and signed self-contained access tokens from channels till API Service Provider 

 decrypt and use clear self-contained access tokens in case of internal communication (Ex: Inter Microservice, Inter app communication)





Refresh Token	

A refresh token is a credential used to obtain a new access token when the original access token issued by an authorization server expires.

 use Refresh token in case of Experience APIs 





Opaque Token	

An opaque token is a type of security token, that doesn't reveal its internal information or structure directly to the client. Opaque tokens are typically represented by a unique identifier or reference during token introspection the associated access token is identified and used by the API service provider.

 use Opaque token in case of Open APIs when there is a limitation to use Self-Contained Encrypted Access Tokens due regulatory or compliance specific requirements 










	API.TStd.310

	
3.16.3 Registered JWT Claims
Role: Application Owner/API Developer


Claims are assertions that one subject (e.g. a user or an Authorization Server) makes about itself or another subject. 

Claim	Definition/Purpose/Guideline	Data Type	Value Case Sensitive	ID Token	Access Token	Refresh Token
sub (Subject)	
The "sub" (subject) claim identifies the principal that is the subject of the JWT.

The PEP Component/API Service Provider  verify the subject claim represent the intended user or entity.  reject if subject is incorrect.







Scenario	Claim Value	ID Token Example	Access Token Example
In case of Retail, where Customer is the subject.	Relationship ID	

"Relationship ID" Value in obfuscated/hashed form. 

{
    "iss": "sc:auth-server:server-id",
    "sub": "<RelID-Hash>",
}

	

Value in Clear - (Encrypted Token, North-South Traffic)

{
    "iss": "sc:auth-server:server-id",
    "sub":"<RelID-Clear>",
}


In case of Corporate Banking, Entity End User is the Subject	End User ID	

"End User ID" Value in obfuscated/hashed form.

{
    "iss": "sc:auth-server:server-id",
    "sub": "d5f22f83be74826b0f9ce03f0ea81a697f09701c",
}

	

Value in Clear - (Encrypted Token, North-South Traffic)

{
    "iss": "sc:auth-server:server-id",
    "sub": "452561",
}


In case of Service-to-Service Communication, Service ID namespace is the subject.	

Service ID namespace.

Example

"sc:system:CEMS"

	NA	

Value in Clear - (Clear Token, East-West Traffic)

{
    "iss": "sc:auth-server:server-id",
    "sub": "sc:system:source-system",
}










Act On Behalf: Ex: Contact Center/RM/Ops User acting on-behalf of Customer.

The acting party is the Subject. 

	

Should Include the Acting Party Identifier.

Examples

Contact Center User ID or
RM ID or
Ops User ID
	"Acting Party ID" value in obfuscated/hashed form if internet traffic otherwise clear.	

Value in Clear - (Clear Token, East-West Traffic)

(Encrypted Token, North-South Traffic)

{
    "iss": "sc:auth-server:server-id",
    "sub": "452561",
}







	String		

	

	


iss (Issuer)	




The "iss" (issuer) claim identifies the principal that issued (Identity Server) the JWT.

The value  be an URI

The PEP Component/API Service Provider  verify the issuer of the JWT matches the expected value, if not  reject the token.




{
    "iss": "sc:auth-server:server-id",
    "aud": [ "sc:system:target-system"],
    "nbt": 1526435855433,
    "iat": 1526435833433,
    "exp": 1526436165154,
}




	String		

	

	


aud (Audience)	

The "aud" (audience) claim identifies the recipients (Ex: Application/System URI) that the JWT is intended for.

The PEP Component/API Service Provider  verify the audience is the intended recipient. if not  reject the token.

Each principal intended to process the JWT  identify itself with a value in the audience claim.   be a registered URI.

If the principal processing the claim does not identify itself with a value in the "aud" claim when this claim is present, then the JWT  be rejected.




{
    "iss": "sc:auth-server:server-id",
    "aud": [ "sc:system:target-system"],
    "nbt": 1526435855433,
    "iat": 1526435833433,
    "exp": 1526436165154,
}




	Array of Strings		

	

	


exp (Expiration Time)	

The "exp" (expiration time) claim identifies the expiration time on or after which the JWT  be accepted for processing.

The PEP Component/API Service Provider  verify the JWT is not expired.

 reject expired tokens to prevent replay attacks.

Its value  be a number containing a NumericDate value.

The processing of the "exp" claim requires that the current date/time  be before the expiration date/time listed in the "exp" claim.

The Token expiry for ID Token  be set to "2" minutes subsequently renewed based on refresh token. 

The Token expiry for Access Token  adhere to the ICS Timeout Standards or Regulatory standards.




{
    "iss": "sc:auth-server:server-id",
    "aud": [ "sc:system:target-system"],
    "nbt": 1526435855433,
    "iat": 1526435833433,
    "exp": 1526436165154,
}




	Numeric Date	
	

	

	


iat (Issued At)	

The "iat" (issued at) claim identifies the time at which the JWT was issued.

This claim can be used to determine the age of the JWT.

The PEP Component/API Service Provider  verify the token was issued in a reasonable timeframe.

 reject if unreasonable past or feature tokens.

Its value  be a number containing a NumericDate value.




{
    "iss": "sc:auth-server:server-id",
    "aud": [ "sc:system:target-system"],
    "nbt": 1526435855433,
    "iat": 1526435833433,
    "exp": 1526436165154,
}




	Numeric Date	
	

	

	


acr (Authentication Context Class Reference)	

It is used to convey information about the level of authentication that was performed during the authentication process. It provides a way to indicate the strength or trustworthiness of the authentication method used.

The Standard doesn't mandate what names to use for LOAs. Each domain can define their names based on the business requirement.   All the LOAs  be registered in the Identity Server 

The PEP Component/API Service Provider  validate "acr" claim to determine the strength of the Authentication.

 Ensure that the "acr" claim aligns with the required authentication context.

Authentications with the lowest LOA  be used to authorize access to any resource of any monetary value.

An absolute URI or an RFC 6711 registered name  be used as the "acr" value.




Retail Domain Example

Level of Assurance Name 

	Description
0	Device Authentication
1	Facial Recognition / Fingerprint biometric.
2	Password based Authentication.
3	Multi Factor Authentication

{
    "iss": "sc:auth-server:server-id",
    "aud": [ "sc:system:target-system"],
    "nbt": 1526435855433,
    "iat": 1526435833433,
    "exp": 1526436165154,
    "acr": "sc:loa:3"

}




	Array of Strings		

	
	

amr (Authentication Methods References)	

JSON array of strings that are identifiers for authentication methods used in the authentication.

For instance, values might indicate that both password and OTP authentication methods were used.




Each Identity Provider  support one or more Authentication Method References based on the requirement. 

The PEP Component/API Service Provider  validate "amr" claim to understand the Authentication methods used.

 Ensure the "amr" claim aligns with the required secure authentication methods.

Names used in the "amr" Claim  be from those registered in the IANA Authentication Method Reference Values registry [IANA.] established by [RFC8176];

Registered Names  be used for a different meaning.

Usage of Custom un-registered names  be agreed upon with all parties. 







Authentication Method Reference Name Examples	Description
face	Facial Recognition
fpt	Fingerprint biometric.
geo	Geolocation
iris	Iris Scan biometric
kba	Knowledge based Authentication.
mca	Multiple Channel Authentication
mfa	Mutiple Factor Authentication
otp	One-time Password
pin	Personal Identification Number or Pattern
pwd	Password based Authentication.
sms	Confirmation using SMS
tel	Confirmation by Telephone call

{
    "iss": "sc:auth-server:server-id",
    "aud": [ "sc:system:target-system"],
    "nbt": 1526435855433,
    "iat": 1526435833433,
    "exp": 1526436165154,
    "amr": "mfa"

}







	Array of Strings		

	
	

azp (Authorized Party)	

The party to which the ID Token was originally intended to issue.

If present, it  contain the OAuth 2.0 Client ID of this party.

The PEP Component/API Service Provider  validate "azp" claim to identity the Authorized Party.

 Ensure the "azp" claim corresponds to the expected and authorized party.




{
    "iss": "sc:auth-server:server-id",
    "aud": [ "sc:system:target-system"],
    "nbt": 1526435855433,
    "iat": 1526435833433,
    "exp": 1526436165154,
    "azp": "authorized-client-id"

}




	
		

	
	

jti (JWT ID)	

The "jti" (JWT ID) claim provides a unique identifier for the JWT helps to prevent the JWT from being replayed.

The PEP Component/API Service Provider  prevent the JWT token re-use using jti.

The identifier value  be assigned in a manner that ensures that there is a negligible probability that the same value will be accidentally assigned to a different token.

if the application uses multiple issuers, collisions  be prevented among values produced by different issuers as well.




{
    "iss": "sc:auth-server:server-id",
    "aud": [ "sc:system:target-system"],
    "nbt": 1526435855433,
    "iat": 1526435833433,
    "exp": 1526436165154,
    "jti": "unique-identifier(Ex:UUID)"

}




	
		

	

	


scopes	

The "scopes" claim is used to convey the specific permission or access levels granted to the client application, often used during authorization process.

Scopes in the Access Token  be used as coarse-grained access control attributes from PEP/Gateway perspective fine -grained from application-level perspective.




{
    "iss": "sc:auth-server:server-id",
    "aud": [ "sc:system:target-system"],
    "nbt": 1526435855433,
    "iat": 1526435833433,
    "exp": 1526436165154,
    "scope": "profile"

}

Refer Section Scopes for more details.

	
		
	

	








	API.TStd.320

	
3.16.4 Custom JWT Global Claims
Claim	Definition/Purpose	Data Type	Value Case Sensitive	ID Token	Access Token	Refresh Token
country	
	string				

itam	for observability purposes	string	
	
		





	API.TStd.330

	
3.16.5 Scopes

Scopes are groups of claims.

3.16.6 Default Scopes

The OpenID Connect specification only defines a single set of standard scopes:

Scope

	

Claims


email	




email







address

	




address




email_verified







profile

	




name




family_name




given_name




middle_name




nickname




preferred_username




profile




picture




website




gender




birthdate




zoneinfo




locale




updated_at







phone

	




phone_number




phone_number_verified







openid

	




sub




auth_time




acr




3.16.7 Custom Scopes
Role: Application Owner/API Developer





Each application implementing Coarse-Grained Authentication at PEP level  define the required scopes and register them in the central Authorization Server. 

 limit custom scope usage to Coarse-Grained Authentication and Fine-Grained Authentication to be addressed at Application level.

Custom Scopes  have a well-defined and Clear Purpose, indicating the specific access or functionality they grant.

 follow Consistent Naming convention to enhance clarity and maintainability.

 use Descriptive Labels that convey their intended functionality to both developers and end-users.

The permissions associated with each custom scope  be Clearly Documented, specifying exact actions or data access it grants.

Custom Scopes  Avoid Ambiguity.

Custom Scopes  align with application Authorization model.

Identity/Authorization server  validate the input parameters related to custom scopes to prevent injection or manipulation.




Scope (Example)

	Claims (Examples)
payee	




payee:create




payee:read




payee:update




payee:delete




payee:list





payment	




payment:book-transfer




payment:create-local-transfer




payment:transaction-history





transfers	




transfer:book-transfer




transfer:telegraphic-transfer




transfer:local-transfer










	API.TStd.340

	
3.16.8 Consent and Claims
3.16.8.1 Sharing Data with a Third-party Platform (TPP)

Consent is an important way for Third Party Clients to inform the user about data that is being shared.

PSD2 requires user consent for banks to share customer account information with TPP's.

Regulators such as European Commision mandate PSD2 compliance, necessitating user, consent for banks to share customer account information with Third-Party Providers (TPPs)

Role: Application Owner/API Developer and/or Platform/Infrastructure Owner





Consent for Claims  be required from User in case of Open APIs where the client is a third-party platform (Ex: Account Aggregators, FinTech's). 

TPP Platform  redirect the customer to Banks Platform to give his/her consent to share the data. 

Identity Server  offer a screen to select or unselect the set of claims to share with the client (Third-party).

In case where selection is not possible, the action  result in releasing "All" claims or "Nothing" 




3.16.8.2 Act-on-Behalf. 

Role: Application Owner/API Developer and/or Platform/Infrastructure Owner





User Consent  be provided for on-behalf scenarios (Ex: Customer Calling Contact Center Agent to update his/her profile or asked to perform certain actions). 

 use only Banks approved methods (Web Form, OTP, Push Notification, Biometric etc.) for capturing user content.

The choice of method chosen  be based on the business requirement and approved by Architecture & Security Counsil also should adhere to regulatory and market requirements.   







	API.TStd.350

	
3.16.9 Token Revocation
Role: Application Owner/API Developer and/or Platform/Infrastructure Owner


Access tokens and refresh tokens will expire at some point in time.

Access tokens tend to expire quickly, whereas refresh tokens last longer.

Their validity period is set when created. The period for which they are valid depends on factors such as:

How the user authenticated and when
The client application that was used
The scopes that the user delegated.

Other contextual information can be considered when setting the duration of validity as well.

When a token is about to expired before this time, it should be revoked.

The JWT Token endpoint typically get invoked in the below scenarios.

#	Scenario	Revocation By
1	User Logout	Client
2	User Account Deactivation	API Provider
3	Token Compromise or Theft	Client, API Provider
4	Change in User Permissions or Roles	API Provider
5	Token Expiry Mangement	API Provider, IDP Admin

For Scenario 2-5 the client is not aware of the Revocation, Hence the client  perform a periodic check to validate the token by calling the user-info endpoint. 




Aspect	Details
Endpoint URL	




The API endpoint for revoking tokens  follow RFC 7009 standard.

The client  send the token along with the credentials to the revoke endpoint.

The Identity server  return an empty body with a HTTP status code 200.

A "hint" about the token type (access_token, refersh_token, opaque)  be send as part of the body or parameter.

If the hint is wrong or not understood, but the token found, then Identity server  still revoke the token.




Request Parameters

Method: POST
Content-Type: application/x-www-form-urlencoded
Response Type: json
Parameter	Value	Mandatory	Description
client_id	The Client ID	yes	The ID of the requesting client
client_secret	The client secret	yes*	The secret of the client. *Mandatory if client authentication is of type secret, and the authentication is not done using basic authentication
token_type_hint	access_token or refresh_token	no	Can be sent to inform the server of the type of token, if not sent the server will attempt to figure out the token type.
token	A token	yes	The token to revoke

Response

If Http Status 200 then Token revocation successful, otherwise fail.





Revoking Opaque Token	

Opaque Tokens are by-reference tokens.

This means there is a corresponding access token at the backend which has all the identity data.




Opaque access tokens can be revoked and  become inactive in the moment of revocation.

on revocation event the identity server  notify the API producer about the Token revocation.




if refresh token is still live, new access tokens can still be issued for the client without additional user interaction.





Revoking Access Token	

Access Tokens are by-value tokens.

This means that all identity data and metadata are in the token itself.

One piece of metadata is the expiration time. These tokens can be revoked like any other; however, the consumer (i.e., back-end API) of these tokens might not notice this revocation.

on revocation event the identity server  notify the API producer about the Token revocation.





Revoking Refresh Token	

The Refresh Token is the root of all delated access tokens. Many access tokens  be issued for the same Refresh token.

When an access token is revoked only that token is cancelled.

When the refresh token is revoked, the entire delegation  be revoked.










	API.TStd.360
3.17 API Keys
Incoming Index	Technical Standard Statement	Technical Standard Index

	




Role: Application Owner/API Developer





Applications (API Consumer & API Provider) developed and managed internally or externally  only use token-based authentication unless not supported due to COTS dependency can consider API Keys.

API Keys  be Kept Confidential and not exposed or shared via insecure channel.

 use Secure Channel HTTPS (TLS) when transmitting API Keys to prevent eavesdropping and unauthorized access.

API Keys  be Hard Coded to avoid unauthorized exposure.

API Keys  be Unique per user or application to facilitate tracking monitoring and enforcement of usage policies.

 implement API Keys Expiration and Renewal mechanisms.

 adhere to Banks Standards Key Management practices for Key Issuance and Key Rotation. Refer ICS Cryptography Standard for more details.







	API.TStd.370
3.18 Mutual TLS Authentication (mTLS)
Incoming Index	Technical Standard Statement	Technical Standard Index

	

Mutual TLS (mTLS), also known as two-way TLS or client certificate authentication (Aka X509 authentication), involves two parties: the client and the server.

Each party presents a digital certificate during the TLS handshake process, and both parties authenticate each other.

Role: Application Owner/API Developer





API provider (SCB) certificates  be signed by SCB CA and/or by external trusted CA.

Client Certificates  be signed by the external CA trusted by the Bank.

 use mTLS for East-West Traffic unless a COTS application dependency.

Private and Public certificates  be issued and managed centrally.

Private and Public certificates  be rotated securely and regularly.

Private and Public certificates  be stored securely within applications and systems - API consumers and API providers.

Only bank approved Private and Public certificates algorithms  be used.

Version Cipher Suite
TLS 1.2 Reference: TLS Cipher Suite Guidelines
TLS 1.3 Reference: TLS Cipher Suite Guidelines







	API.TStd.380
3.19 Automated API Abuse Protection
Incoming Index	Technical Standard Statement	Technical Standard Index

	




Role: Application Owner/API Developer and/or Platform/Infrastructure Owner








Aspect	Guideline
Rate Limiting	

Platform/Infrastructure Owner  ensure that APIs implement rate limiting mechanisms to restrict the number of requests from a single client within a defined time period.

Refer section Rate Limiting for more details.


Bot Protection	Platform/Infrastructure Owner  ensure that Internet facing Experience APIs are enabled with Bot Protection capabilities at Edge level (Ex: Akamai BMP)
Challange Response	

API Owner/API Developer  ensure Pre-Authenticated Internet facing APIs implement a CAPTCHA challenge for suspicious or high-volume requests to prevented automated abuse.

Implementation of CAPTCHA Challange  be optional if APIs accessed over Mobile App using Anonymous Device Binding.

 implement CAPTCHA for APIs for browser-based traffic. 

Consideration of exceptions to CAPTCHA implementation, which may impact customer experience will only proceed following a comprehensive security risk assessment endorsed by Architecture and Security Council and approved by CISO.   





Anonymous Token	

API Owner/API Developer  implement Anonymous Token to prevent direct access to pre-Authenticated APIs.

Anonymous tokens are temporary credentials (per session) issued based on the unique (Hard to spoof) identification of a client (Ex: Mobile Device Binding ID) to prevent DoS attacks.

For mobile app traffic, anonymous device binding  be utilized to generate the token, while for web applications, creating a sophisticated, difficult-to-spoof unique identity on the browser side is necessary.


SMS OTP Flood Attack	

Internet facing Experience Pre-Authenticated APIs handling SMS OTPs are prone to SMS Flood Attacks.

 Consider below controls in addition to above.


	

Mobile Number Logging	

API Provider  Keep track of all the mobile numbers attempted. 


OTP Count	

API Provider  Track the count of OTP requests made for each mobile number during the OTP journey.


OTP Generation	
 Limit the generation of OTPs per session (Ex: 3) and per day (Ex: 20) for each mobile number

OTP Cool Down	

OTP Cooldown refers to the period of time during which a user must wait before they can request another OTP after the previous one has been issued. Cooldown enhances security by limiting the frequency of OTP requests.

 Implement OTP cooldown. (Ex: 1 minute per OTP)


Blacklisting	
API Provider  Maintain a blacklist of known malicious phone numbers and block any new requests from these numbers.

Mobile Number & Geolocation Validation	

API Provider  Restrict sending of SMS OTPs to International and Premium numbers using Geolocation at Application level or at SMS service provider level.

API Provider  should only allow mobile numbers relevant to the location in scope.

API Request with other location mobile numbers  be blocked/rejected. 

Location Tracking can be done by IP Address or GPS based if Mobile traffic. However, there are certain limitations to each option. 

Refer Securing Pre-Authenticated APIs for more details.





Anonymous Device Binding	

Experience pre-authenticated APIs accessed via Mobile app  enforce device binding.

Device binding Authentication  be implemented using strong cryptographic methods to ensure the security of device identifiers.

Devices  be uniquely identified combining hardware-based identifier and cryptographic keys. 

APIs  perform a secure device registration/deregistration.

Refer API Protection Through Anonymous Device Binding for more details.













	API.TStd.390
3.20 ACL Vulnerabilities
Incoming Index	Technical Standard Statement	Technical Standard Index

	
3.20.1 IDOR & BOLA
Role: Application Owner/API Developer and/or Platform/Infrastructure Owner








Aspect	Guideline
Access Controls	

APIS  Enforce strong access controls to restrict access to resources based on the authenticated user's permissions.

 apply Coarse-Grained Access controls at PEP level and Fine-Grained Access control at API Provider Level. 

Context of the user and application  be validated appropriately before responding to any API calls.


Contextual Authorization	

API Provider  Implement contextual authorization, considering User Roles, Attributes, or other contextual information to determine access rights. 

API access at functional level and data level  be vetted at API Provider (FAP / DAP checks)

API owning application (real backend)  respond with API data only when both contexts are verified, and ACLs applied.


Unique Identifiers	

APIs  use Unique, Immutable and securely generated Indirect Object Identifiers (Ex: UUID) to avoid easily guessable or sequential references that could lead to IDOR vulnerabilities.

 avoid encrypting identifiers when its challenging to generate Indirect Object Identifiers.


Rate Limiting	

Platform/Infrastructure Owner  ensure APIs implementing specific API Rate Limits to mitigate brute-force, enumeration attacks that could lead to successful IDOR exploitations. 


Malicious Reconnaissance	

Platform/Infrastructure Owner APIs  employ measures to detect and mitigate malicious reconnaissance activities, including but not limited to unauthorized probing for sensitive resources, directories, or endpoints.

API server  respond to reconnaissance attempts with appropriate HTTP status codes (Ex: 403 Forbidden, 404 Not Found) to restrict unauthorized access and avoiding disclosing sensitive information. 

APIs  implement logging and monitoring mechanisms to track and analyze suspicious requests, enabling timing detection and response to reconnaissance activities.










	API.TStd.400




3.21 Input Validation & Data Sanitization
Incoming Index	Technical Standard Statement	Technical Standard Index

	

Input validation is performed to ensure only properly formed data is entering the workflow in an information system, preventing malformed data from persisting in the database and triggering malfunction of various downstream components. Input validation should happen as early as possible in the processing pipeline.

Role: Application Owner/API Developer





Data from all potentially untrusted sources  perform input validation that includes internet facing web clients, backend-feed over extranets, partners, regulators.

All input (Request Parameters, Path Variables, Request Body) received by the API provider  undergo through validation to ensure it adheres to expected formats, lengths, and data types.

Input validation  be performed at the Earliest Point in the processing Pipeline to prevent potentially malicious or malformed data from entering the system.

 Sanitize all incoming data (Query Parameters, Request Body and Headers) by Stripping or Escaping potentially harmful characters to prevent Injection Attacks, such as SQL Injection or Cross-Site Scripting (XSS).

 use parameterized Queries (Ex: Prepared Statements) provided by the programming language or framework and avoid Dynamic SQL generation to prevent SQL Injection attacks.

 Perform Input validation and data sanitization on both client-side and server-side to ensure multi-layered defense against malicious input.

In case of failed Input validation, APIs  log detailed information, including the requester's IP address, user-agent HTTP header, and the specific input data triggering the validation failure.

Logging of failed input validation  adhere to Sensitive Data Handling requirements. Refer Logging for more details.

 Utilize Industry-Standard libraries or frameworks for input validation and sanitization.

 Reject or Sanitize any input that violates the predefined constraints, provide appropriate error responses to inform clients about the validation failure.

 Perform Regular Review of the Input Validation Rules to adapt to evolving security threats.







	API.TStd.410




3.22 Content-Type Header Validation
Incoming Index	Technical Standard Statement	Technical Standard Index

	




Role: Application Owner/API Developer





All incoming requests  include a valid 'Content-Type' header.

API Server  enforce strict validation of the 'Content-Type' header,  reject unexpected or unsupported 'Content-Type' values.

Clients  use appropriate and standardized media types in the header 'Content-Type' such as 'application/json' or 'application/xml' based on the nature of the payload.

Refer Content-Type HTTP Standard Headers section for the supported media types.

API Server  process requests with missing or invalid 'Content-Type' header. 

APIs  clearly specify the expected 'Content-Type' for each endpoint in the documentation.

API Server  provide informative error responses when encountering invalid or unsupported 'Content-Type' header.

API Consumers  include character set information in the 'Content-Type' header for textual content. (e.g., 'application/json; charset=utf-8')

 use UTF-8 encoding for all text-based media types.







	API.TStd.420




3.23 Transport Security
Incoming Index	Technical Standard Statement	Technical Standard Index





PCD-130

	

Transport security ensures the confidentiality, integrity and authenticity of data during transit, protecting from eavesdropping, tampering and unauthorized access.

Role: Application Owner/API Developer and/or Platform/Infrastructure Owner








Aspect	Guideline
TLS (Transport Layer Security)	

All APIS  use TLS for secure transit, ensuring encryption of data in transit between clients and servers.

APIs (Internal) that use gRPC protocol for inter-microservice communication  be at exception not to use TLS decided based on risk with threat modelling.


Minimum TLS Version	

All TLS version  be a minimum of 1.2 or higher to mitigate vulnerabilities associated with older TLS versions.

TLS 1.2 –  be configured.

TLS 1.3 – Good to have.

TLS 1.1, TLS 1.0, SSL 3.0, and other SSL versions –  be used.

 Refer SCB Acceptable TLS Cipher Suites for latest version.


Cipher Suite	

ALL APIs  only support the Bank approved secure strong cipher suites.

Refer below link for more details.
TLS 1.2 Reference: TLS Cipher Suite Guidelines
TLS 1.3 Reference: TLS Cipher Suite Guidelines


Strict Transport Security (HSTS)	

APIs accessed via Web Browser clients  implement HSTS to enforce the use of secure connection and protect against man-in-the-middle attacks.


Certificate Signing & Verification	

APIs must be protected with certificates issued by SCB CA.

External facing APIs  be protected with certificates signed by external CA.

APIs  use any self-signed certificates.

 perform Certificate Chain Verification.

 use Expired Certificates

Platform/Infrastructure Owner  ensure APIs perform Certificate Revocation checking by using Certificate Revocation Lists (CRLs) or Online Certificate Status Protocol (OCSP) for external APIs.


Certificate Pinning	

Platform/Infrastructure Owner  ensure Internet facing APIs use Certificate Pinning by associating a host with its expected certificate or public key.










	API.TStd.430




3.24 Data Security
Incoming Index	Technical Standard Statement	Technical Standard Index





PCD-090

PCD-110

PCD-130

	
3.24.1 End-to-End Encryption (E2EE)

The most secure API is the one that avoids unwrapping the payload mid-transit this includes (Request Body, Headers, Query Parameters).

WAF

However, for security purposes, traffics undergoes unwrapping to facilitate inspection for DDoS protection, Layer 4 examination and examination of SNI details etc.

Reverse Proxy

During reverse proxying, traffic becomes clear when TLS termination occurs at the proxy server, allowing the payload to be decrypted for inspection or processing before forwarding it to the backend servers.

Payload Encryption & Signing

Payload level encryption (to satisfy data confidentiality requirements) and/or signing (to satisfy data integrity requirements) are alternate options to ensure system interactions are protected when traffic gets intercepted at Edge and proxies.

Security Architecture or SACA Team to assess the need for End-to-End Encryption.

Payload signing  be used to address non-repudiation requirements. 

Role: Application Owner/API Developer and/or Platform/Infrastructure Owner








Aspect	Guideline
E2EE	

 use one of the below methods to implement E2EE based on the technical feasibility and complexity.

Method 2  be considered if explicit requirement by third-party.

External Internet Facing APIs (Experience, Open API, Partner) carrying sensitive data  use only approved secure transport TLS. (For Version details Refer SCB Acceptable TLS Cipher Suites)

 terminate TLS traffic at Edge.

 do reverse-proxy at Edge level instead  perform forward-proxy with SNI support.

 apply WAF controls within banks network.




External Facing APIs (Experience, Open API, Partner) carrying sensitive data  use payload level encryption to ensure confidentiality during transmission.

 Utilize Industry-Standard libraries or frameworks for encryption and decryption.

 use Asymmetric Encryption for smaller payloads

 use Envelope Encryption with Session key (Dynamically Generated, Short Lived, Symmetric Key) for large payloads with internet facing clients.

 use Envelope Encryption (DEK, KEK) or with Session Key for partner APIs over private network.

Decryption

 ensure encrypted payloads gets decrypted only within the API Service Provider in a secure manner. 

Signing & Verification

External Facing APIs (Experience, Open API, Partner) carrying sensitive data  use payload level signing to ensure data integrity and authenticate the sender.

 apply WAF controls at the API server level as the traffic couldn't be intercepted at the Edge level due to double encryption.





Tokenization & Masking	

API providers  send by default masked PCD (Credit Card/Debit Card Number) data to web client APIs.

Access to clear PCD data only available after appropriate MFA method is performed.

API providers  send by default tokenized PCD data to internal API consumers, if API consumers are capable of processing tokenized data.

API providers  never send tokenized data to external third-party consumers (Open APIs, Partner APIs).

 use only CaaS platform solution for Tokenization & Detokenization

 use only the bank approved Token Formats (Ex: Tokenize Middle 6 digits of the PAN)

PAN Tokenization Example

Refer PCI DSS Standards for more details on tokenization and Masking.


Algorithms	

 use only bank approved crypto algorithms.

Refer ICS Cryptography Standard for more details.


Secure Key Management	

 secure key management practices to safeguard encryption and signing keys from unauthorized access.

 Use only use bank approved encryption symmetric and asymmetric algorithms.

Encryption keys  be issued and managed centrally.

Encryption keys  be rotated securely and regularly.

Encryption keys  be stored securely within applications and systems - API consumers and API providers.

Only bank approved digital signature algorithms  be used.


Payload Size Consideration	

 Evaluate the impact of encryption on payload size and choose appropriate algorithms to balance security and efficiency


JWT Sensitive Claim Integrity and Confidentiality 	

There may be a feature scenario where a secret needs to be embedded as part a claim, for performance and availability reasons.

For such instances the tokens  be encrypted and signed.










	API.TStd.440




3.25 CORS (Cross-Origin Resource Sharing) Policy
Incoming Index	Technical Standard Statement	Technical Standard Index

	

CORS security control restricts web page access to resources on a different origin (domain). It prevents unauthorized cross-origin requests initiated by scripts running in a web browser.

CORS headers, such as 'Access-Control-Allow-Origin', 'Access-Control-Allow-Methods' are to be sent by API Sever to instruct the browser on which origins are permitted to access the resources and what HTTP methods are allowed.

3.26.1 CORS Headers and Purpose
Header	Purpose
Access-Control-Allow-Origin	Specifies which origins are allowed to access the resource.
Access-Control-Allow-Methods	specifies which HTTP methods are allowed when accessing the resources.
Access-Control-Allow-Headers	Indicates which HTTP headers can be used during the actual request.
Access-Control-Allow-Credentials	

Indicates weather the browser should include credentials (like cookies or HTTP Authentication) when making the actual request.

if set to 'true' it allows credentials.




Role: Application Owner/API Developer





When Web Clients wants to access cross origin resources, then Web APIs  enforce CORS policies to control access from browsers.

CORS policies  be configured to allow only specific origins (domains) that are necessary for legitimate API consumers.

Web API responses  include CORS headers 'Access-Control-Allow-Origin' to specify allowed origins.

APIs  allow unrestricted access using wildcard ('*') in the 'Access-Control-Allow-Origin'

Web API responses  include CORS header 'Access-Control-Allow-Methods' to specify the allowed HTTP Methods.

Web API responses  include CORS header 'Access-Control-Allow-Headers' to specify which headers can be used during actual request.

Web API responses  include CORS header 'Access-Control-Allow-Credentials' to specify whether to include credentials.

API server  handle preflight requests by responding appropriately to HTTP OPTIONS requests with necessary CORS headers.

API Documentation  clearly specify the CORS requirements for each endpoint, including allowed origins and supported methods. 







Access-Control-Allow-Origin: https://cross.domain.com
Access-Control-Allow-Methods: GET, POST, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization
Access-Control-Allow-Credentials: false

Refer RFC 6454 for more details.







	API.TStd.450




3.26 Rate Limiting
Incoming Index	Technical Standard Statement	Technical Standard Index











	

Rate limiting controls the rate or frequency at which requests are made to a system, service or API within a time frame. It's employed to prevent abuse and ensure fair usage and protect against DDOS or brute force attacks, that enhances the availability of online services.

Role: Application Owner/API Developer and/or Platform/Infrastructure Owner





Platform/Infrastructure Owner  ensure APIs are protected using rate limiting mechanisms to prevent API abuse.

Platform/Infrastructure Owner  ensure Different definitions of Rate Limiting are considered like IP based, concurrency based, geolocation based in order to address high-availability, DDoS protection, BOT attacks, Password Spray attacks, Malicious File Upload attacks etc.  

Platform/Infrastructure Owner  define and apply domain specific (Ex: sc.com, customer.sc.com, payment.sc.com) rate limiting policies.

Platform/Infrastructure Owner  define and apply custom rate limiting policies based on API Criticality, Data Sensitivity (Ex: PII, PCD).

Platform/Infrastructure Owner  ensure Pre-Authenticated/Anonymous APIs traffic should be kept at minimum as they are vulnerable to BOT attacks,  implement dedicated rate limiting policy with lower/minimum threshold.

Platform/Infrastructure Owner  ensure APIs implement additional rate limiting controls specific to their business capability (Ex: Maximum SMS delivered per client)

Requests Exceeding the defined rate limits  result in a response with the appropriate HTTP status code (e.g., 429 Too Many Requests)

API Owner/API Developer  document the rate limits on how its calculated and enforced.

Platform/Infrastructure Owner  include a Retry-After header in responses with HTTP status code 503 (Service Unavailable).







	API.TStd.460




3.27 Data Minimization
Incoming Index	Technical Standard Statement	Technical Standard Index

	

Data minimization is a principle in information security and privacy that advocates for limiting the collection, processing, and retention of personal or sensitive information to only what is strictly necessary for a specific and legitimate purpose. The goal of data minimization is to enhance user privacy, reduce the potential for misuse or abuse of collected information, and mitigate the impact of data breaches.

Role: Application Owner/API Developer








Aspect	Guideline
Limit Scope	

APIs  limit the collection and processing user data to only what is strictly necessary for intended purpose.


Anonymize or Pseudonymize	

API providers  anonymize or pseudonymize user data to reduce the impact of a potential breach.

API providers  send by default masked PCD (Credit Card/Debit Card Number) data to web clients.

Access to clear PCD data  only available after appropriate MFA method is performed.

API providers  send by default tokenized PCD data to internal API consumers that support tokenization.

API providers  never send tokenized data to external third-party consumers (Open APIs, Partner APIs)

Refer PCI DSS Standards for more details on tokenization and Masking.


Explicit Consent	

Data collection beyond essential information  require explicit user consent.

APIs  adhere to privacy policies and inform users about data processing activities.


Granular Access Controls	

APIs  implement granular access controls to restrict access to data based on user roles and permissions.

Only authorized entities  have access to specific data sets.


Rate Limiting	API Rate Limiting  be performed by the API Gateway / PEP










	API.TStd.470
3.28 Idempotency
Incoming Index	Technical Standard Statement	Technical Standard Index

	

Idempotency essentially means that the effect of a successfully performed request on a server resource is independent of the number of times it is executed.

3.28.1 Idempotency with HTTP Methods

An idempotent HTTP method is a method that can be invoked many times without different outcomes. It should not matter if the method has been called only once, or ten times over. The result should always be the same.

If we follow the REST principles in designing our APIs, we will have automatically idempotent REST APIs for GET, PUT, DELETE, HEAD, OPTIONS, and TRACE methods. Only POST and PATCH APIs will not be idempotent.

HTTP Method	Idempotent	Safe
GET		
HEAD	

	
PUT		


DELETE		


POST	

	


PATCH	

	




Role: Application Owner/API Developer








Principle	Guideline
Use Appropriate HTTP Methods	

 use GET for read-only operations.

 use PUT, DELETE for state-changing operations.

 use PATCH for state-changing operations.




Hint	Details	Example
Statelessness	

Ensure PATCH operation is self-contained doesn't rely on server's state between requests.

	

Idempotent Operations	Design the PATCH operation to produce the same result when applied multiples times.	Updating a resource to set a field to a specific value should not change the resource if it already has that value.
Idempotency-Key	Use Idempotency keys like UUIDs or Tokens to prevent duplicate changes to the resource.	




HTTP/1.1 200 OK
PATCH /resource/123
Content-Type: application/json
Idempotency-Key: abc123
{
"field": "value"
}





Atomicity	Ensure PATCH Operation either succeeds entirely or fails without partially modifying the resource.	Use database transactions to ensure that all updates are applied atomically.
Error Handling	Handle errors gracefully and provide information error messages to assist clients in understanding the cause of the failure.	

Return appropriate error status codes (Ex: 400 Bad Request, 409 Conflict) with descriptive error message. 








Use Unique Client Request Identifiers (UUID)	

 Include unique identifiers in requests to distinguish between requests.


Use Idempotent Token	

 Use idempotent tokens in request to prevent duplicate processing.


Response Status Codes	

 use appropriate HTTP status codes to indicate success or failure.


Retry Mechanism	

For failed requests, client  implement retry logic with exponential backoff and jitter.

Exponential Backoff

Start with a small retry interval.
Double the retry interval after each consecutive failure.
Set a maximum retry interval to avoid waiting indefinitely.
Implement a cap on the number of retry attempts.

Jitter

Introduce randomness to the retry intervals to avoid synchronized retries. 
Randomly adjust the retry interval within a certain range.
Use uniform or exponential distributions for generating jitter.
Ensure that the jitter does not exceed a certain percentage of the base retry interval.

 Utilize Industry-Standard libraries or frameworks (Ex: Resilience4j)

for exponential backoff and jitter implementations.





Failure Handling	

Failures  be handled consistently and safely.

 use Retry-After Header in response.

Refer RFC 7231 Section 4.2.2 for more details.







	API.TStd.480
3.29 File Upload Security
Incoming Index	Technical Standard Statement	Technical Standard Index

	

API file upload security involves safeguarding the process of uploading files through an API. it includes measures such as authentication, authorization, validation of file types and sizes, and encryption to protect against security threats and ensure secure handling of uploaded files.

 implement the below guidelines to help prevent malicious activities and ensures the confidentiality and integrity of the uploaded data.

Role: Application Owner/API Developer








Aspect	Guideline
Authentication & Authorization	

 Ensure only authenticated users has the privilege to upload the files.

 implement only approved authentication mechanisms based on API Type and validate user's permission before allowing file uploads.

Refer Authentication Patterns


Use Secure Protocols	

 transmit files over secure channels TLS to prevent eavesdropping and data tampering.

 Use only approved secure transport TLS. (For Version details Refer SCB Acceptable TLS Cipher Suites) 


File Type Validations	

API Providers  prevent execution of malicious files by verifying the file types.

 implement strict file type validation on the server-side to ensure that only permitted file types are accepted.

 trust Content-Type header as it can be spoofed.


File Size Limitations	

 mitigate DoS/DDoS attacks by limiting the size of uploaded files.

 define and enforce reasonable file size limits to prevent large files from overwhelming the sever.


Limit Chunked Encoding Size & POST Size	

 enforce maximum size limit for individual chunks in chunked encoding and maximum size limit for HTTP POST requests to prevent resource exhaustion.


File Name	

 change the filename to something generated by the application.

Include

Aspect	Description
Timestamp	To Indicate when the file was generated.
Unique Identifier	

Use Unique Identifier to ensure uniqueness to avoid filename collision.

Ex: UUID


Content Description	

Include brief description of the file content to provide context.

Ex: Account_Statement_123456789.pdf


User or Session ID	if the file generated in response to a specific user action or session, include userId or sessionId.
File Format Extension	

Ensure the file name includes the appropriate file format extension.

Ex: .pdf, .csv etc


Version	

If the file is part of a series, then include version number in the filename.

Ex: document_v1.2.pdf







 set filename length limit in consideration with OS and filesystem limitations.

 restrict the allowed characters.

Reserved Characters

Certain Character are reserved by operating systems or file systems and cannot be used in file names.

Windows: \/:*?"<>| 
Unix/Linux: /(forward slash) and null character (\0)

Whitespace Characters

space
tab
newline

Control Characters

Carriage return
line feed.

Special Characters

leading or trailing periods (.)
backticks (`)
dollar signs ($)
percent signs (%)





File Extension	

 allow only safe and critical extensions for business functionality







File Type	File Extension
Executable Files	.exe, .dll, .bat, .com
Script files	.sh, .bash, .ps1
System Files	.sys, .ini
Configuration files	.config, .xml
Database files	.sql, .db, .mdb
Source code files	.cpp, .java, .py
Shortcut files	.lnk
Batch files	.bat, .cmd







 perform input validation before validating the extensions.


File Checksum	

API client  calculate checksum for each file upload to ensure data integrity during transmission and storage.

API Provider  verify checksum provided by the client against the calculated checksum. of the uploaded file. 

 use bank approved hashing algorithms for checksum calculation.

APIs  reject the file upload if checksum fails.


Malware and Virus Scan	

 protect the system from malicious files by scanning uploaded files for malware and viruses.

 use bank approved antivirus and malware scanning tools and perform scan from a secure Sandbox.


Slowloris Dos attack Prevention	

Slowloris is a type of denial-of-service attack, which uses partial HTTP requests to open connections between a single computer and a target webserver, then keeping those connections open for as long as possible, thus overwhelming and slowing down the API server.

Web Servers/API Servers  implement connection limits per IP address to mitigate the Slowloris attacks.

File upload APIs  be configured with custom Tailored Rate Limiting Policies, to restrict the number of requests per IP Address.

 use IDS/IPS capabilities to detect and block Slowloris attack patterns.

API Server  capture and route all File upload activity logs to Central Observability Platform and SIEM.

SIEM  be configured with specific rules to detect and alert Slowloris attacks.










	API.TStd.490
3.30 Runtime Security
Incoming Index	Technical Standard Statement	Technical Standard Index

	




Role: Platform/Infrastructure Owner





APIs  apply Runtime Security on the following aspects.

Aspect	Guideline


Traffic Visibility

	

 have real-time visibility into API traffic, including request, response and header information.




Anomaly Detection

	

 Implement anomaly detection mechanisms to identity unusual patterns or behaviors into API traffic, indicating potential threats.




Rate Limiting

	

All Internet facing APIs and Internal reuseable APIs  implement rate limiting to prevent abuse, denial -of-service attacks, and ensure fair usage of API resources.

Refer section Rate Limiting for more details.




Payload Inspection

	

 perform payload inspection for malicious content, including SQL Injection, cross-site scripting (XSS) and other injection attacks.




Behavior Analytics

	

 apply behavior analytics to identity deviations from normal API usage patterns, aiding in detection of potential security incidents.


Security Headers	 Enforce secure HTTP headers to mitigate common web security vulnerabilities, such as Cross-Site Scripting (XSS) and Clickjacking
Incident Response Integration	API Infra  Integrate with the Banks SIEM to trigger incident response plan, allowing for immediate action in the event of a security incident.










	API.TStd.500
3.31 Threat Protection
Incoming Index	Technical Standard Statement	Technical Standard Index





	




Role: Platform/Infrastructure Owner





APIs  be protected against external Threats. 

Aspect	Guideline
Granular Policy Definition	
 define granular security policies at individual domain level and API specific level (Policy Ex: Rate Limiting Policy, Bot Protection Policy) 

OWASP Web & API Top 10 	
 use Edge as the first touchpoint for inbound internet facing API traffic (Experience APIs, Open APIs, Partner APIs) to protect against OWASP top 10 threats

WAF	

All API traffic  route through the WAF layer to protect against Web and DDoS attacks.

 only forward authorized and secure traffic by the Edge to the SCB network.










	API.TStd.510




3.32 Logging & Monitoring
Incoming Index	Technical Standard Statement	Technical Standard Index


TMT.EM.EM.OC01

TMT.EM.ED.CR01 

	
3.32.1 Logging
Role: Application Owner/API Developer








Aspect	Guideline
Log Level	

Logging levels such as DEBUG, INFO, WARN and ERROR  be clearly defined.

 Use appropriate log levels based on the severity and importance of the logged events.


Log Format	

 define standardized log format that includes essential information such as timestamp, log level, source and message.

 include contextual information such as request IDs, user IDs, and correlation IDs to facilitate log aggregation and analysis.

Minimum attributes to be captured as per ICS SLM Standards.

Attribute	Definition


Event Type

	

Describes the nature or type of event being logged, often focusing on the specific action, condition, or occurrence that triggered the log message.




Event Type	Log Entry When
API Request	 API request received.
API Response	API response sent to client.
Error	Error during API Request processing.
Authentication	User or Client Authenticates.
Authorization	Authorization checks performed.
Access Control	API Policy/PEP enforced.
Validation	Input validation checks performed.
Audit	Specific Events or Actions recorded.
Cache	Cache mechanisms are utilized.
Integration	API Interactions with external systems or services










Event Source

	

 log the API event source (Ex: ITAM ID or SUB claim value (User ID, Customer ID, Server Name etc) from the token to identify consumers and channels)

API Gateway
API Service
Authentication/Authorization Server
Client Application etc.







Use Identifier (if applicable)

	




User ID
Username
Email
Employee ID
Phone Number etc.







Data and timestamp.

	
2022-03-25 14:30:00 UTC



Host Identifier (If applicable)

	




Hostnames
IP Address (Utilize the X-Forwarded-For header to record initial origin of the IP address)
FQDNs
Server Instance Names
Container Identifiers
Cluster Names
Service Names
Gateway Identifiers







Event Description

	




User Authentication

Description: "User 'Sam' successfully authenticated with username and password."

API Request

Description: "Received GET request from '/api/v1/products' from IP address '192.168.1.100'."

Data Modification

Description: "Updated customer record with ID 'CUST-123' to change the email address."

Error Handling

Description: "Failed to process request due to invalid input parameters."

File Upload

Description: "Uploaded File 'document.pdf' with Size '2.5 MB' to the server." 

Resource Access

Description: "User 'admin' access restricted resource '/admin/dashboard'."

Security Incident:

Description: "Detected multiple failed login attempts from IP address '203.0.113.10'"







Event Severity

	




DEBUG
INFO
WARNING
ERROR
FATAL
TRACE







Task Category

	

Provides a categorization or classification of log message based on the type of task or activity being performed within the application.

Typically used to organize log entries into meaningful group or categories such as database operations, authentication events, network requests etc.

Database
Authentication
File System
Error Handling
Performance
Security
etc







Log Type

	

Typically refers to classification or categorization of log messages based on their purpose, content or intended use. Makes it easier to manage, analyze and interpret log data.

Error Logs - Indicate errors or exceptions.
Warning Logs - Indicate potential issues or abnormal conditions does not result in error.  
Informational Logs -
Debug Logs - Contains detailed information for troubleshooting purposes.
Audit Logs - Records actions or events related to security, compliance or regulatory requirements.
Access Logs - Including HTTP requests, API calls and user sessions. Used to track usage patterns, analyze traffic and detect suspicious activity.
Performance Logs - Captures Performance metrics, such as response times, resource usage and throughput.
etc








Sensitive Data Handling	

 avoid logging sensitive information such as passwords, access tokens, PII or PCD data.

 implement redaction or masking techniques to protect sensitive data if logging is necessary.





Log Retention and Rotation	

 define log retention policies specifying the duration logs should be retained.

 implement log rotation mechanisms to manage log file size and prevent storage exhaustion.

 consider archival and backup strategies for long-term log storage and compliance purpose.


Log Transport and Storage	
All API logs  be shipped and stored into central logging systems and having sufficient capacity hold the logs as per standard.
 use secure transport protocols (Ex: TLS) for transmitting logs to central logging systems.
 encrypt log data at rest to protect from unauthorized access. 

ICS Standards	
All API logs events  be meet logging requirements as per ICS SLM standards.  Refer ICS SLM Standards for more details.







3.32.2 Tracing

Role: Application Owner/API Developer





APIs  support distributed tracing for end-to-end visibility.

Tracing information  be propagated consistently across microservices.

 Implement standardized trace context propagation mechanisms, such as W3C Trace context.

 propagate traceparent and tracestate headers.

Example:

GET /api/resource HTTP/1.1

Host: example.com

traceparent: 00-0af723423432cd234234345443-01

tracestate: somevendor=somevalue, anothervendor=anothervalue

 support OpenTelemetry specification

 ensure traced information adheres to privacy and security regulations.

Header X-Forwarded-For  be used when OpenTelemetry is not available to perform end to end tracing of requests.

Given the possibility of IP Spoofing, X-Forwarded-For  be used for validating the clients.










	API.TStd.520


TMT.EM.EM.OC01

TMT.EM.ED.CR01 

TMT.EM.ED.CR02

RES.SAC.CC.OC01

	
3.32.3 Monitoring
Role: Platform/Infrastructure Owner





API infrastructure  meet monitoring requirements and configurations as per the guidelines.

3.33.4 API Usage Metrics

Metric Category	Examples	Mandatory	Capture Location
Request Metrics

	

Total Requests

		

PEP/API Gateway
Application










Requests per Minute

	


Requests per Hour

	
Response Metrics	

Average Response Time

	


95th Percentile Response Time

	

Error Rate Metrics	

Error Percentage

	


Error Types (exx, 5xx)

	

Latency Metrics	

Network Latency

	


Server Processing Time

	
Traffic Source Metrics	

Origin of Requests (Mobile, Web)

	
	
Edge/Front Door
PEP/API Gateway





Geographical Distribution

	

Authentication Metrics	

Successful Authentications

	
	
PEP/API Gateway
Application

















Failed Authentication Attempts

	
Concurrency Metrics	

Simultaneous Connections

	



Peak Concurrency

	

Rate Limiting Metrics	

Request Allowed

	



Requests Exceeding Limits

	
Consumer Adoption Metrics	

Unique API Consumers

	



Growth in Use Base

	

Endpoint Popularity





	

Most Frequently Accessed Endpoints

	



Least Used Endpoints

	



Trending Endpoints

	

Deprecation and versioning

	

Deprecated version usage

	


Adoption of new Versions

	


Version update impact

	







	API.TStd.530
3.33 Documentation and Specifications
Incoming Index	Technical Standard Statement	Technical Standard Index








	




Role: Application Owner/API Developer








Aspect	Guidelines
Endpoints Documentation	
API documentation  include comprehensive details. for all API endpoints, specifying their purpose, methods and parameters.

Open API Specification (OAS)	

API documentation  be provided in the Open API Specification (OAS) format adhering to the standard schema for clarity and consistency.

 follow contract-first approach, rather than an implementation-first approach. 

 use tools like swagger to generate documentation from API contracts.

Since the OAS specification evolves,  follow the latest standard of OAS specification.

Reference - OAS 3.0 (https://www.openapis.org/)


Request/Response Formats	
Request and Response formats, including data types and structures  be clearly defined for each API endpoint.

Examples	

API documentation  include representative examples for common use cases to illustrate proper request and response structures.


Authentication Requirements	
Authentication requirements, including supported authentication methods  be clearly documented for each API endpoint.

Rate Limiting Information	

Rate Limiting policies and usage guidelines  be documented, specifying the allowed number of requests within a given timeframe.

Example:

Users are limited to 100 requests per minute for the '/search' endpoint. 


Detail Error Response	
Error responses, including possible HTTP status codes and corresponding error messages  be documented comprehensively. 

API Version	
API Versioning  be documented and guidelines for versioning  be provided.

Change Log	
Change log  be maintained in API documentation, outlining additions, modification, deprecations over time.

Interactive Documentation	
Tools like Swagger UI  should be integrated to allow developers to explore and interact with API directly from the documentation.
3.33.1 gRPC Documentation




Documentation Aspect	Guidelines
Service Definition	
 provide clear and precise documentation for all ROC methods defined in the '.proto' file.
 include descriptions of each RPC method's purpose, input parameters and output messages.

Message Structure	

 document all message types defined in the '.proto' file, including their fields and data types.

 provide examples illustrating the usage of each message type in different RPC methods.


Error Handling	

 define handling mechanisms for RPC methods, including error codes and descriptions.

 explain how clients should handle errors returned by gRPC services and provide guidance on error recovery strategies.


Security Considerations	

 address security considerations such as authentication, authorization and data protection.


Versioning and Compatibility	 document backward and forward compatibility guidelines













	API.TStd.540
3.34 API Resilience
Incoming Index	Technical Standard Statement	Technical Standard Index


RES.RM.RA.CR01

RES.CAP.CP.CR01

RES.CAP.CP.CR02

	




Role: Platform/Infrastructure Owner





All API Infrastructure  be deployed with sustained/uninterrupted resilience to avoid any service failures on components level.
All API Components  be deployed with local/remote high availability to meet resilience availability standards.
API Traffic  be segregated to minimize the blast radius.
 consider implementing bulkhead pattern when services are complex, critical and have external dependencies.
 use bulkhead when simple, low risk services, limited resources, highly coupled and having performance overheads. 
 use the same API Gateway to publish North-South and East-West traffic.
if API Gateway used, they  be segregated by API Type (Open API, Partner API, Experience and Internal APIs) 
API  be unavailable for scheduled maintenance, and  have pre-planned scheduled outage window."


API Resilience Testing




Aspect	Details
Failure Injection	

Platform/Infrastructure Owner  ensure proper setup and configuration of failure injection mechanisms in test environments and analyze the impact of overall system resilience.  


Recovery Mechanisms	

Platform/Infrastructure Owner  ensure Infrastructure supports effective recovery mechanisms and validate their functionality in restoring API services after failure events.







Role: Application Owner/API Developer


API Resilience Testing

Aspect	Details
Objective Definition	
Resilience testing  have clearly defined objectives, including identifying weakness, validating recovery mechanisms, and ensuring service availability under stress conditions.

Tet Scenario Design	

Test scenarios  encompass various failure scenarios, including network failures, service outages and resource exhaustion. 

Services  be designed to simulate real-world conditions and stress the API under different failures modes.


Failure Injection	

Resilience testing  involve injecting failures into the system to evaluate its response under adverse conditions.

Failure injection techniques  be controlled and measured to ensure safety and predictability.


Graceful Degradation	

APIs  gracefully degrade in functionality under stress or failure conditions, rather than completely failing.

Degradation thresholds  be defined, and APIs  continue to provide essential services even when degrade.


Recovery Mechanisms	

APIs  be tested for their ability to recover from failures and restore normal operation.

Recovery mechanisms  be validated under different failure scenarios to ensure effectiveness and reliability.


Performance Metrics	

Resilience testing  measure key performance metrics such as response time, throughput, and error rates under stress conditions.

Metrics  be collected and analyzed to identity performance bottlenecks and areas for improvement.


Scalability Testing	

Resilience testing  include scalability testing to evaluate the APIs ability to handle increasing loads and scale resources dynamically.

Scalability testing  be integrated into the broader resilience testing plan to assess the APIs resilience under varying traffic conditions.










	API.TStd.550
3.35 Deployment
Incoming Index	Technical Standard Statement	Technical Standard Index

	




Role: Application Owner/API Developer and/or Platform/Infrastructure Owner





API Owner/Developer  ensure APIs are deployable across diverse environments, including cloud platforms, on-premises servers and hybrid infrastructures, to ensure flexibility and scalability.
API Platform/Infra Owner  ensure API deployment process is automated and reproducible using configuration management tools and infrastructure as code practices (IaC).
API Owner/Developer  ensure Deployment scripts and procedures are well documented, version-controlled, and tested to ensure consistency and reliability across environments.
API Owner/Developer  ensure API deployments are containerized to ensure consistent runtime environments.
API Owner/Developer  ensure APIs support multiple deployment approaches to minimize service disruption during updates.
API Platform/Infra Owner  ensure Deployment Processes are designed to minimize downtime and service interruptions, ensuring high availability and reliability of API services.


Deployment Approaches




Approach	Guideline
In-Place Deployment	

API Owner/Developer  use in-place deployment for minor updates or fixes that are low-risk and have been thoroughly tested and certified in pre-production environment.

API Owner/Developer  use in-pace deployment for major updates or changes that could potentially disrupt service availability or require extensive rollback procedures.

API Platform/Infra Owner  ensure adequate monitoring and rollback procedures are in place to mitigate the risk of service disruptions during in-place deployments.


Canary Deployment	

API Owner/Developer  consider Canary Deployment for rolling out new features or updates to a small subset of users or traffic segments to validate changes in a controlled environment.

 API Platform/Infra Owner  offer tools or platform that support Canary Deployments.


Blue-Green Deployments	

API Owner/Developer  use Blue-Green deployment for significant updates or releases that require zero downtime deployment and easy rollback capabilities.

API Owner/Developer  use Blue-Green deployment if maintaining two identical production environments is not feasible or cost-effective, or if updates being deployed are minor and low-risk.

API Platform/Infra Owner  facilitate blue-green deployments by provisioning and managing duplicate production environments, ensuring seamless switching between environments during updates.

API Platform/Infra Owner  introduce complex or manual process for managing blue-green deployments that could introduce operational overhead and risk of configuration errors.


A/B Deployment	

API Owner/Developer  consider A/B deployment for testing new features or variations in the API behavior to gather user feedback and make data-driven decisions on feature releases.

API Platform/Infra Owner  support A/B deployment by providing tools and platforms for managing traffic routing and monitoring the performance of different API versions or configurations. 

API Platform/Infra Owner  support A/B deployment if there are concerns around the impact of overall system stability.













	API.TStd.560
Annexes
A. Informative Annex
B. Reference

No.

	

Reference


1	API Design Guidelines