Strengthen API Security with OpenAPI

Janet Wagner
by Janet Wagner on September 27, 2023 5 min read

When you think about API security, does OpenAPI ever come to mind? Well, it should. OpenAPI — a specification language for HTTP APIs — has many features and tool choices that can help you strengthen the security of your APIs. The key to security with OpenAPI lies in its clarity and openness — you can better understand how your APIs will behave and how users will interact with them, making it easier to secure them. You also get multiple, well-tested security patterns built into the specification language, so you can control how and when you address security for your APIs.

Build On the Stable Foundation of OpenAPI

If you don’t understand how your API will behave, then you can’t secure the API properly. Using a standardized format for describing APIs can help you better understand your API and prepare for known and unknown security issues. You can use OpenAPI to detail every part of your API — from endpoints and operation parameters to request responses and authentication flows. And its format is easy for humans and machines to read and understand. 

OpenAPI has been widely adopted by the API developer community, so most members of your API team will likely already be familiar with and understand it. Your team knows what they’re getting with this specification, and so will your users. Plus, OpenAPI forms the foundation for numerous industry-standard tools to build APIs — design, code, documentation, observability, and more.

Adopt Well-Tested Security Practices

When it comes to security, you shouldn’t reinvent the wheel. Follow well-trodden paths for security so you can focus your expertise on your API products.

OpenAPI refers to authentication and authorization schemes as “security schemes.” It supports proven security methods, although security schemes differ among the different OpenAPI versions. For example, OpenAPI version 3.0 supports more security schemes and bearer formats than version 2.0, and OpenID Connect Discovery was added to this version. This blog post explains the differences between OpenAPI versions 2.0, 3.0, and 3.1.

OpenAPI version 3.1 supports these security schemes:

  • HTTP authentication — Supports basic authentication and bearer authentication, including JSON web token (JWT) bearer. You can also describe APIs with HTTP schemes defined by the HTTP Authentication Scheme Registry and RFC 7235. Both basic and bearer authentication use HTTP headers to authenticate users. Bearer is more secure than basic because API requests are harder to intercept.   
  • API Key — Many APIs use an API key, a unique identifier that verifies the identity of the application or user making the request to the API. You can insert the key in a request header, cookie parameter, or query string. You should always apply additional security protocols when using an API key, such as TLS/SSL, which means the API URLs will start with HTTPS.
  • OAuth2 — These flows rely on or grant types that allow the user or client to share data from the resource server with an access token from the authorization server. OpenAPI 3.1 supports common OAuth2 flows, which include authorization code (the most common flow), implicit, password, and client credentials.
  • Mutual TLS — Mutual Transport Layer Security (mTLS) is a security method involving two-way or mutual authentication between the server and the client. Typically, the client will present a trusted certificate for API requests.
  • OpenID Connect Discovery — This is a discovery mechanism in OpenID Connect, where an OpenID server makes its metadata available through a “well-known” URL. OpenAPI allows you to describe the OpenID Connect Discovery security scheme for your API.

All of these are well-tested, well-supported protocols that meet a wide range of security needs. Starting with a schema that supports all of them allows you to adjust your approach to API security without having to rebuild everything. Following standard security practices helps reduce the risk of API vulnerabilities because everyone is on the same page and approaching security in the same way.

You should also consider using automation or AI to tackle cybersecurity because there are too many sources of risk for one team to tackle it all. Plus, most cybersecurity incidents occur because of human error

Shifting Security Left Without Shifting Focus

“Shift left.” You probably hear this term a lot, especially if you’re a member of a development team. Many companies today want DevOps teams to shift left, which practically speaking means testing quality and performance applications as early as possible in the development process, before writing code. When teams shift left, they can better anticipate problems that could impact quality, performance, and delivery.

You may be wondering how you can test an API if you haven’t coded it yet — that’s where OpenAPI comes in. You can design and describe your APIs with OpenAPI and then generate realistic mock servers from your OpenAPI documents (with help from a tool like Stoplight Studio or Prism!). API mocking means you create a copy, imitation, or simulation of a real API, allowing you to obtain realistic responses.

You should think about security as early as possible in the development lifecycle, adopting a DevSecOps (DevOps + Security) approach. Focusing on security early in the design stage helps address potential problems before you reach the coding stage. Fixing security issues before you’ve coded an API is much easier and less costly.

Better API Security and Quality with OpenAPI

Leveraging OpenAPI can help you improve your security posture without compromising your ability to deliver excellent API products. It enables you to do this by:

  • Putting tools, documentation, and common design patterns in easy reach
  • Providing clear pathways for implementing security standards

Don’t wait to address the security of your APIs. Use OpenAPI to focus on security early to help prevent costly and time-consuming API vulnerabilities.

Share this post

Stoplight to Join SmartBear!

As a part of SmartBear, we are excited to offer a world-class API solution for all developers' needs.

Learn More
The blog CTA goes here! If you don't need a CTA, make sure you turn the "Show CTA Module" option off.

Take a listen to The API Intersection.

Hear from industry experts about how to use APIs and save time, save money, and grow your business.

Listen Now