API Policy Document

API Policy Document

 API Policy Document

Document Control
Document Name API Best Practices
Classification Internal
Version Number Version 1
Audience
Date 14th November 2024
Reviewed & approved by
Review frequency Annually
Last Reviewed 14th November 2024

Revision History
Date Version Description Created by Revised by
Draft Document API Team NA

Commented [H/1]: API Versioning Strategy

Deprecation policies

API key management

Token expiration policies
Credential storage mechanisms

Timeout configurations
JWT Token Security
 API Policy Document

Table of Content
1. Introduction....................................................................................................................................... 4
2. Scope .................................................................................................................................................. 5
3. API Security Objectives ................................................................................................................ 6
4. Authentication & Authorization................................................................................................. 6
4.1 Authentication ................................................................................................................................. 6
4.2 Authorization ................................................................................................................................... 6
5. Rate Limiting, Throttling & Spike Arrest ............................................................................. 7
5.1 Rate Limiting .................................................................................................................................... 7
5.2 Throttling ........................................................................................................................................... 7
5.3 Spike Arrest ...................................................................................................................................... 7
6. Error Handling ................................................................................................................................ 7
7. Input & Output Validation ......................................................................................................... 9
8. Logging & Monitoring .................................................................................................................. 9
8.1 Logging .............................................................................................................................................. 9
8.2 Monitoring ......................................................................................................................................... 9
9. Network Security ........................................................................................................................... 9
10. API Endpoint Security .............................................................................................................. 11
11. Security Headers ........................................................................................................................ 11
12. Third-party Integrations ......................................................................................................... 11
13. Regular Security Audits ........................................................................................................... 11
14. Repository Management ......................................................................................................... 11
 API Policy Document

1. Introduction
The purpose of this API Best Practices Document is to outline a framework that governs the secure
interaction between users, applications, and ICICI LOMBARD's APIs. This document is in
compliance with ICICI LOMBARD’s API security document and elucidates the best secure practices
that must be adhered to by all stakeholders engaging with the API. By establishing a clear and
formalized set of rules and expectations, this document aims to:
 Implement strong authentication and validation measures to ensure data security.
 Streamline interactions for user and application ease.
 Eliminate ambiguity by offering clear instructions and requirements.
 Counteract potential risks through verification.
 API Policy Document

2. Scope
The scope of this API Best Practices Document ensures a comprehensive framework that addresses
all the guardrails implemented by the company to establish a secure API ecosystem that minimizes
risks and vulnerabilities. The framework includes:
 API Security Objectives
 Authentication & Authorization
 Data Protection
 Rate Limiting & Throttling
 Error Handling
 Input & Output Validation
 Logging & Monitoring
 Audit Trails
 Network Security
 API Endpoint Security
 Security Headers
 Third-Party Integrations
 Security Incident Response
 Regular Security Audits
 Training & Awareness
 API Policy Document

3. API Security Objectives

 The objectives stated below collectively form a comprehensive strategy to establish a secure
API ecosystem that minimizes risks and vulnerabilities while maximizing the benefits of
seamless application integration and communication
 Authentication & Authorization: Only authorized users, applications, or systems must
access and interact with the API. Any exception to this requirement, either temporary or
permanent, has to be discussed and approved by ISG.
 Data Confidentiality: Sensitive data transmitted between client and server must be
protected from unauthorized access or interception
 API Rate Limiting & Throttling: Abuse, overuse, or denial-of-service attacks must be limited
the number of requests from a single client or IP address
 Input Validation & Sanitization: API must be protected from vulnerabilities and attacks by
adhering to standard procedure of ISG
 Error Handling & Reporting: Secure and informative error messages must be provided to
both developers and users without revealing sensitive information that could be exploited
 Security Auditing & Logging: API activities must be monitored and tracked for security
incidents, suspicious behaviour, and compliance purposes
 Third-Party Integration Security: The third-party APIs used in application must adhere to
ISG security standards to prevent vulnerabilities from being introduced through external
components.

4. Authentication & Authorization

4.1 Authentication
 Strong password policies must be implemented for length, complexity, and special
characters.
 Communication between clients and the company API must be encrypted using HTTPS, TLS
and/or equivalent technology to prevent data interception and tampering.
 Regular security audits must be conducted to identify vulnerabilities in systems as per IL
schedule
 Strong mechanisms such as OAuth protocol or equivalent should be implemented to access
APIs.
 Explanation of API authentication method and guidance on setting up authorization,
including required headers, tokens, or API Scope and other necessary details.

4.2 Authorization
 Authorization Token must be sufficiently complex or as per the global standards.
 Attributes that affect access control decisions must be identified in-order to grant or deny
access and implement a logic to make dynamic access decisions.
 API Policy Document

5. Rate Limiting, Throttling & Spike Arrest

5.1 Rate Limiting
 Types of Rate Limiting Techniques that must be implemented are:
o User-based rate limiting
o Global rate limiting
 Rate Limiting must be applied at multiple levels for fortifying defences against misuse and
overload. Some standard practices for rate limiting include client ID-based rate limiting,
endpoint-specific rate limiting, and tiered rate limiting to manage access based on client
importance, API sensitivity, and service levels.
 Regular review of rate limits must happen to assess their efficacy and impact on legitimate
traffic. This is applicable on per application per API basis as and when needed.
 Rate limiting and API Quotas must be implemented to restrict number of requests made by
single user/application or IP address.

5.2 Throttling
 Number of requests a client can make within a given time window must be clearly defined.
 Limit on the number of simultaneous connections from a single client must be defined.
 Burst Allowance must be minimum.
 Different API throttling mechanism which must be applied are:
 Fixed Window Throttling
 Dynamic Throttling
 Throttling must be configured differently for different clients, depending on factors such as
subscription tier, user role, or the type of application.
 Developers/Users consuming APIs must be aware of the rate limits imposed by the API and
handle the 429 responses appropriately.

5.3 Spike Arrest

 Define the time interval over which the request rate is measured. Shorter intervals can
prevent sharper spikes, while longer intervals can smooth out bursts of traffic.
 Decide how to handle requests that exceed the limit. Rejecting requests is straightforward
but can lead to a poor user experience. Queuing requests can smooth out processing but
may lead to increased response times.
 Implement logging and monitoring to track when the spike arrest is triggered. This can help
in analysing traffic patterns and adjusting policies as needed.

6. Error Handling
 The error messages must be informative and suggestions to resolve these errors must be
provided.
 API Policy Document

 Swift identification and resolution of errors must be expedited by the API Documents to
spotlight any discrepancies or concerns within the response, thereby expediting
troubleshooting efforts for users
 User Interpretable error outputs should be defined
 API Policy Document

7. Input & Output Validation

 All APIs must incorporate comprehensive input validation mechanisms to prevent the
processing of erroneous or malicious data, and output data must be sanitized to eliminate
security vulnerabilities.
 Security monitoring must be implemented at all operational levels of the API infrastructure
to detect, alert, and respond to any unauthorized or anomalous activities.
 Dashboard is required to display critical security metrics, including the frequency and nature
of input validation failures, to support effective security oversight.
 The API Gateway is must to utilize defensive measures against a range of threats and other
prevalent attacks like code injection threats, Distributed Denial of Service (DDoS), Phishing,
Man-in-the-Middle attack to ensure secure database interactions across the API ecosystem.

8. Logging & Monitoring

8.1 Logging
 Audit logs or monitoring mechanisms that are in place must be described for user
management.
 API Security Gateway must log and monitor API Traffic and integrate logs with SIEM
(Security Information and Event Management).
 SIEM (Security Information and Event Management) systems are designed to provide a
comprehensive view of an organization's information security. It is suggested that
organisation must have network monitoring, log management; should have compliance
reporting, user activity monitoring; and good to have data loss prevention (DLP) monitoring
and cloud security monitoring.
 Input validation errors and extra parameters errors, crashes and core dumps must be
logged.

8.2 Monitoring
 The usage, performance, and potential issues of an API must be regularly monitored.
 Regular monitoring and gathering of feedback after changes must be done to identify any
unexpected issues or opportunities for improvement.
 Centralized architecture like an API Gateway should be used for provisioning and governing
access to microservices.
 A central dashboard displays the status of various services and the network segments that
link them.

9. Network Security
 API Communication must be established with strong ciphers with TLS versions such as TLS
1.2 or TLS 1.3 or any other equivalent technology.
 Representational State Transfer (REST) principles must be implemented, such as using
HTTPS methods (GET, POST) appropriately.
 SSL Certificates or equivalent must be used to establish a peer-to-peer trust relationship.
By means of these certificates all incoming and outgoing XML messages or any other
language messages must be encrypted/decrypted and sent by way of HTTPS for efficiency.
 API Policy Document

 API Scope should be confined to specific IP addresses only by performing validation &
whitelisting mechanism.
 API Policy Document

10. API Endpoint Security

 Client requests must be filtered, and unwanted geographies should be blocked.
 Rate limiting is a must, in-order to prevent unreasonable access and block DDoS attacks.
 SSL/TLS certificates and IP whitelisting should be used as security measures wherever
applicable.

11. Security Headers

 Security headers are essential for APIs as they provide an additional layer of defence by
enforcing strict security protocols and mitigating common vulnerabilities. They ensure
secure data transmission and help in maintaining the integrity and confidentiality of the API
communication.
 CORS, CSP, HSTS, X-Content-Type-Options, X-XSS-Protection, Cross-Site-Scripting (XSS),
and Authorization Headers should be used as per the ISG guidelines.

12. Third-party Integrations

 Before the integration, vendor assessment must be performed wherever required or
necessary, by evaluating their security reputation and practices.
 Code changes must be evaluated via integration testing along with sign-off for production
usage.
 API gateway or proxy must be used to manage and secure interactions with third-party API.
 Robust logging must be implemented to track API usage and potential security incidents.
 For the maintenance of the Third party API repository, please use the provided template -

API Repository
Template External Integration.xlsx

13. Regular Security Audits

 Regular security audits must be conducted to identify vulnerabilities in authentication
systems.
 The policy must be reviewed and updated periodically within a fixed duration as per ICICI
Lombard standards to adapt to changing security needs.
 Regular review of API Architecture should be conducted to ensure its continued
effectiveness, reliability, and alignment with evolving needs and technologies.

14. Repository Management

API Repository
 For the maintenance of the API repository, please use the provided template -  Template.xlsx

15. API Versioning Strategy

 API Policy Document

 Each API version must have a clear, unique identifier to distinguish between different
iterations.
 Backward compatibility must be maintained for a predefined period during version
transitions.
 Deprecated versions must have a clearly communicated sunset timeline.
 Clients must be notified well in advance about upcoming version changes and support
window.

16. API Key & Token Management

 API keys must be generated using cryptographically secure random number generators.
 Token expiration policies must be strictly defined:
o Short-lived access tokens (15-60 minutes)
o Longer-lived refresh tokens with secure rotation mechanisms
 Credential storage must implement:
o One-way salted hashing
o Encryption at rest
o Protection against rainbow table attacks
 Mandatory periodic credential rotation for all API consumers

16.1 JWT Token Security

 JWT tokens must include:
o Compact claims set
o Minimal sensitive information
o Cryptographically signed using strong algorithms
 Validate token signature, expiration, and issuer on every request
Implement robust token revocation mechanisms

16.2 Timeout Configurations

 Define connection timeouts for different API interaction types
 Use claim-based access control for granular permissions
 Implement progressive timeout strategies:
o Initial short timeout
o Exponential backoff for retries
 Set maximum retry attempts to prevent infinite loops
 Provide clear error responses for timeout scenario