Get started Bring yourself up to speed with our introductory content.

10 API security guidelines and best practices

As with any software development cycle, API security must be built in from the start. Follow these guidelines to design, deploy and protect your APIs.

APIs are a pivotal element in today's digital world, thanks to the rise of cloud computing and a shift from monolithic applications to microservices. There are now more than 23,000 public APIs, used by millions of developers and hundreds of thousands of organizations around the globe.

As more businesses open up access to data and services through APIs, these vectors present an attractive target for data theft and attacks on software. Insecure APIs are a serious threat -- they are commonly the most exposed component of a network, predisposed to denial-of-service attacks, and easy to reverse-engineer. By the end of 2021, 90% of web-enabled applications will have more attack surface area from exposed APIs than through the UI, up from 40% in 2019, according to Gartner.

APIs create countless opportunities for organizations to improve and deliver services, engage customers, and increase productivity and profits -- but only if you securely implement them. The following best practices can help expand and elevate the security of your organization's APIs.

1. Understand the full scope of secure API consumption

Before you build an application or service that consumes third-party data via APIs, you must fully understand how they work and the correct way to integrate them. Read API documentation thoroughly -- pay particular attention to the process and security aspects of the API's function and routines, such as required authentication, call processes, data formats and any potential error messages to expect. One good approach to this is to build a threat model for your APIs. This will help you understand the attack surface, identify potential security issues and incorporate appropriate security mitigations from the beginning.

2. Validate the data

Never assume API data has been cleansed or correctly validated. Implement your own data cleaning and validation routines to prevent standard injection flaws and cross-site request forgery attacks. Debug tools such as Postman and Chrome DevTools can help examine the API's data flow and keep track of errors and anomalies.

Application and API attack patterns
Exposed APIs are the major attack surface for web-enabled apps. Here's how bad actors cause problems and break in.

3. Choose your web services API: SOAP vs. REST

The two dominant options to access web services via APIs are SOAP (Simple Object Access Protocol), a communications protocol, and REST (Representational State Transfer), a set of architectural principles for data transmission. They use different formats and semantics and require different strategies to ensure robust security. SOAP security is applied at the message level using digital signatures and encrypted parts within the XML message itself. REST relies heavily on access control rules associated with the API's universal resource identifier, such as HTTP tags and the URL path.

Use SOAP if your primary concerns are standardization and security. While both formats support SSL, SOAP also supports WS-Security. It also has built-in error handling, and supports identity verification through intermediaries rather than just point-to-point verification as provided by SSL. However, SOAP exposes components of application logic as services rather than data; this can make SOAP complex to implement, and may require you to refactor an application.

REST, meanwhile, is compatible with various data output types such as JSON, CSV and HTTP, while SOAP can only handle XML and HTTP. Also, REST merely accesses data, so it is a simpler way to access web services. For these reasons, organizations often prefer REST for web development projects.

4. Record APIs in an API registry

Nobody can secure what they don't know. It is essential to record all APIs in a registry to define characteristics such as its name, purpose, payload, usage, access, live date, retired date and owner. This will avoid shadow or silo APIs  -- they have been forgotten, never documented, or were developed outside of a main project, possibly through mergers, acquisitions, or test or deprecated versions. Record details of the information to be logged, such as who, what and when, which will help meet compliance and audit requirements and aid forensic analysis in the event of a security incident.

5. Assess your API risks

Another important API security checklist item is to perform risk assessment for all APIs in your existing registry. Establish measures to ensure they adequately meet security policies and are not vulnerable to known risks. The OWASP API Security Project's Top 10 vulnerabilities list is a good resource to keep tabs on existing attacks and malicious software.

A risk assessment should identify all systems and data impacted if an API is compromised, and then agree to a treatment plan and the controls required to reduce any risks to an acceptable level. Document review dates, and repeat assessments whenever new threats arise or when you modify the API. This documentation should be reviewed prior to any subsequent code changes to ensure security and data handling requirements are not compromised.

6. Be diligent about API documentation

Each API must have a document or manual that contains all technical API requirements, including its functions, classes, return types, arguments and integration processes. Good documentation is particularly important for third-party developers who wish to incorporate those APIs into their own projects. Follow these examples of API documentation best practices, from consistent coverage and syntax to writing to the appropriate audience.

7. Lock down access to APIs

Organizations that want to allow third parties to access internal data and systems through APIs must introduce and test controls to manage that access: who, what and when, as well as checks on data access, creation, update and deletion. Keep APIs behind a firewall, a web application firewall or API gateway -- accessed through a secure protocol, such as HTTPS -- to provide some baseline protection, such as scanning for signature-based threats and injection-based attacks.

Well-designed APIs can also apply rate limits and geo-velocity checks, as well as act as an enforcement point for policies such as geo-fencing and input/output content validation and sanitization. Geo-velocity checks provide context-based authentication by determining access based on the speed of travel required between the previous login and current login attempt.

All these checks are applied by middleware code that is part of the API application. Middleware handles requests before passing them on to be fulfilled.

8. Specify authentication and access

To control access to API resources, you must carefully and comprehensively identify all related users and devices. This typically requires client-side applications to include a token in the API call, so the service can validate the client. Use standards such as OAuth 2.0 and JSON web tokens to authenticate API traffic, and define access control rules, or grant types, that determine which users, groups and roles can access specific API resources.

Always follow the principle of least privilege. If a user just needs to read a blog or post a comment, those are the only permissions to assign to that user.

9. Stash your API keys

API keys identify and verify access for the application or site that calls an API. They can also block or throttle calls made to an API, and identify usage patterns.

API keys are less secure than authentication tokens, and require careful management. Avoid embedding API keys directly in their code or in files within the application's source tree, where they can be accidentally exposed. Instead, store them in environment variables or in files outside of the application's source tree. Better still, use a secrets management service, which protects and manages an application's API keys.

Even with these measures in place, always delete unneeded keys to minimize exposure to attack, and periodically regenerate keys, particularly if you suspect a breach has occurred.

10. Add AI to API monitoring and threat detection

AI-enabled behavior analysis can greatly improve overall API security. It benchmarks normal API traffic and provides visibility into how users access and consume APIs, which can help developers fine-tune threshold settings for context security checks. Threat detection tools can leverage this information to look for anomalous behavior to flag or stop misuse or a potential attack. This approach requires no predefined policies, rules or attack signatures, so it reduces the need for constant updates to stop new and evolving attacks.

Incident response teams should create a plan to handle the alerts produced by threat detection and other security controls, which indicate an API attack.

Dig Deeper on API security