--- title: "Introduction to OpenAPI: 3 Important Security Facts You Need to Know | Phish Protection" description: "The OpenAPI specification has grown popular in the past few years especially when it comes to documenting and describing APIs." image: "https://phishprotection.com/og/blog/introduction-openapi-3-important-security-facts.png" canonical: "https://phishprotection.com/blog/introduction-openapi-3-important-security-facts/" --- Quick Answer The \[OpenAPI\](https://rapidapi.com/blog/api-glossary/openapi/) specification has grown popular in the past few years especially when it comes to documenting and \*\*describing APIs\*\*. This is fueled by the many benefits the specification offers to organizations. Share [ ](https://www.linkedin.com/sharing/share-offsite/?url=https%3A%2F%2Fphishprotection.com%2Fblog%2Fintroduction-openapi-3-important-security-facts%2F "Share on LinkedIn") [ ](https://twitter.com/intent/tweet?text=Introduction%20to%20OpenAPI%3A%203%20Important%20Security%20Facts%20You%20Need%20to%20Know&url=https%3A%2F%2Fphishprotection.com%2Fblog%2Fintroduction-openapi-3-important-security-facts%2F "Share on X/Twitter") [ ](https://www.facebook.com/sharer/sharer.php?u=https%3A%2F%2Fphishprotection.com%2Fblog%2Fintroduction-openapi-3-important-security-facts%2F "Share on Facebook") [ ](https://reddit.com/submit?url=https%3A%2F%2Fphishprotection.com%2Fblog%2Fintroduction-openapi-3-important-security-facts%2F&title=Introduction%20to%20OpenAPI%3A%203%20Important%20Security%20Facts%20You%20Need%20to%20Know "Share on Reddit") [ ](mailto:?subject=Introduction%20to%20OpenAPI%3A%203%20Important%20Security%20Facts%20You%20Need%20to%20Know&body=Check out this article: https%3A%2F%2Fphishprotection.com%2Fblog%2Fintroduction-openapi-3-important-security-facts%2F "Share via Email") ![Phish Protection blog post image](https://media.mailhop.org/phishprotection/images/2022/10/phishing-attack-prevention-7686.jpg) The [OpenAPI](https://rapidapi.com/blog/api-glossary/openapi/) specification has grown popular in the past few years especially when it comes to documenting and **describing APIs**. This is fueled by the many benefits the specification offers to organizations. Some of the notable benefits include the support the specification gets from different [API management tools](https://rapidapi.com/blog/api-management/) and the fact that organizations can generate specifications and documentation from the client side easily. Instead of using XML elements in OpenAPI, developers are required to use **JSON objects**. This comes with a schema used for contents, order, and naming. The JSON file is used to describe all the parts of the API in a standard format. ### What is OpenAPI Specification? Formally known as the [Swagger Specification](https://swagger.io/docs/specification/about/), the OpenAPI specification can be described as an API description format used for REST APIs. With an OpenAPI file, organizations can describe their APIs. The description includes things such as; All[authentication methods](https://www.techtarget.com/searchsecurity/tip/4-API-authentication-methods-to-better-protect-data-in-transit)used. The output and input methods for all endpoints. All the available methods such as **POST and GET**, and endpoints such as URLs. Apart from using the specification to document their APIs, organizations can also use it to **generate client code** and the required documentation. The good news is that most API management tools come with support for Opeation . This not only makes it easy to create APIs but also to maintain them. Some main components you will find with the OpenAPI specification include s\_ecurity, responses, parameters, and paths\_. Each of these components holds **arrays and properties** as JSON objects. You will get descriptions, contact, license, document version, and all the information you need about the APIs in the info field. The server field, on the other hand, describes all the endpoints used in the API. An API can be defined as a **computing interface** that allows applications to communicate and share information. Due to their growing popularity,[cybersecurity](/content/cybersecurity-in-a-nutshell/)has become one of the biggest concerns for organizations. [Cybercriminals](/blog/cybercriminals-are-duping-millions-of-accounts-in-the-latest-facebook-phishing-campaign/) are targeting organizations through APIs to try and **steal information** and data that they access. Here are a few important security facts you need to know about the OpenAPI specification; ![Phishing attack prevention](https://media.mailhop.org/phishprotection/images/2022/10/phishing-attack-prevention-7686.jpg) Where Security is Defined in OpenAPI Specification You can define security in three different places in the OpenAPI specification. These include; Under #/security This is the default place where security is supposed to be defined in the OpenAPI specification. It is also supposed to match with a named [security scheme](https://www.ibm.com/docs/en/api-connect/10%5Freserved%5Finstance?topic=api-defining-security-schemes) that can be or will be found under #/components/securitySchemes. If by any chance you do not define security under #/security or it is found to be an empty object, then your API will not be secured by default. This is common with small APIs that come with **few endpoints** open to most users. However, they define security specific to certain operations. Under #/components/securitySchemes This is the default place for the definition of the security options you have for your API. Smaller APIs normally come with a single option. _You can set anything you want as the key name._ The name you set here will be used when being referenced from anywhere else in the specification. Type is, however, a required parameter. It can be either oauth2, HTTP, apikey, or the new openIdConnect and mutualTLS. All the other parameters change depending on the type used. Under Certain Operations Finally, you can set your OpenAPI security under certain operations. Again, you will use one of[oauth2, HTTP](https://squareball.co/blog/why-oauth-is-better-than-basic-authentication), apikey, or the new openIdConnect and [mutualTLS](https://www.cloudflare.com/learning/access-management/what-is-mutual-tls/). However, this is done under a certain operation that lies on a certain path. If you do not have security defined under certain operations, then the **top-level security** defined under #/security will be used by the API. This is important for APIs with operations that need to use different **security parameters**. ![Phishing definition](https://media.mailhop.org/phishprotection/images/2022/10/phishing-definition-7687.jpg) OpenAPI 3.0 Security Features OpenAPI 3.0 comes with a dedicated part of its document known as security schemes where you are supposed to declare all **security definitions**. The OpenAPI specification has standardized how all the parts of the document are supposed to be declared. This ensures that you can reuse anything declared in the security schemes across different paths without any problems. Previously in OpenAPI 2.0, the shared components were left at the **mercy of developers**. In OpenAPI 3.0, all of them can now be found within the components key . In addition, OpenAPI 3.0 comes with support for OpenID Connect. Organizations are also able to include different oAuth2 flows in their security definitions. This is one of the most popular functionalities today. OpenAPI 2.0 Security Features OpenAPI 2.0 specification comes with a section that is dedicated to the declaration of all security requirements and features used in your API. These security features can be used anywhere in the **API operations and paths**. It also comes with support for a type of security definition known as basic. This is the previous plain[HTTP format of authentication](https://www.ibm.com/docs/en/cics-ts/5.4?topic=concepts-http-basic-authentication). Unfortunately, you will not find any other **built-in security features** with OpenAPI 2.0\. You cannot even define your custom security definitions without having to use extensions provided by external vendors. Even though this is enough for most API security requirements, it might not work well with some special cases. Understanding the security features in both OpenAPI 2.0 and 3.0 is vital in making sure that your APIs are secure . ## Topics [ Cybersecurity ](/tags/cybersecurity/) ![Brad Slavin](https://media.mailhop.org/phishprotection/images/authors/brad-slavin.jpg) [ Brad Slavin ](/authors/brad-slavin/) General Manager Founder and General Manager of DuoCircle. Product strategy and commercial lead across DuoCircle's 2,000+ customer base. [LinkedIn Profile →](https://www.linkedin.com/in/bradslavin) ## Protect your inbox from phishing attacks Real-time email security with 60-day free trial. No credit card required. [Start Free Trial](https://portal.duocircle.com/cart.php?a=add&pid=101&brand=phishprotection) [View Pricing](/pricing/) ## Related Articles [ Intermediate 3m 13,000 Singapore-based students affected as a threat actor hacked into their devices! Aug 16, 2024 ](/blog/13000-singapore-based-students-affected-as-a-threat-actor-hacked-into-their-devices/)[ Intermediate 3m The 2024 Multi-Nation Elections Need to Steer Clear of Highly Potent Cyber Menaces May 9, 2024 ](/blog/2024-multi-nation-elections-cyber-threats-stay-vigilant/)[ Intermediate 6m 7 Commonly Overlooked But Crucial Security Threats That You Might be Ignoring Feb 6, 2023 ](/blog/7-commonly-overlooked-but-crucial-security-threats-that-you-might-be-ignoring/)[ Intermediate 17m 9+ Cybersecurity Software Solutions For Businesses To Use May 30, 2022 ](/blog/9-cybersecurity-software-solutions-businesses/) ```json {"@context":"https://schema.org","@type":"Organization","name":"Phish Protection","url":"https://phishprotection.com","logo":{"@type":"ImageObject","url":"https://phishprotection.com/images/phishprotection-logo.png"},"description":"Advanced phishing protection and email security for businesses. Real-time threat defense, time-of-click protection, and seamless Office 365 integration.","parentOrganization":{"@type":"Organization","@id":"https://www.wikidata.org/wiki/Q138883901","name":"DuoCircle LLC","url":"https://www.duocircle.com","sameAs":["https://www.wikidata.org/wiki/Q138883901","https://www.crunchbase.com/organization/duocircle-llc","https://www.linkedin.com/company/duocircle","https://github.com/duocircle"],"subOrganization":[{"@type":"Organization","@id":"https://www.wikidata.org/wiki/Q138898167","name":"DMARC Report","url":"https://dmarcreport.com"},{"@type":"Organization","@id":"https://www.wikidata.org/wiki/Q138897474","name":"AutoSPF","url":"https://autospf.com"},{"@type":"Organization","@id":"https://www.wikidata.org/wiki/Q138897912","name":"Phish Protection","url":"https://www.phishprotection.com"}]},"sameAs":["https://www.linkedin.com/company/duocircle","https://x.com/duocirclellc","https://www.facebook.com/duocirclellc","https://github.com/duocircle"],"contactPoint":{"@type":"ContactPoint","contactType":"customer support","url":"https://phishprotection.com/contact/"},"knowsAbout":["Phishing Protection","Email Security","Anti-Phishing","Business Email Compromise","Ransomware Protection","Time of Click Protection","Office 365 Email Security","Advanced Threat Defense"]} ``` ```json {"@context":"https://schema.org","@type":"WebSite","name":"Phish Protection","url":"https://phishprotection.com","description":"Advanced phishing protection and email security for businesses. Real-time threat defense, time-of-click protection, and seamless Office 365 integration.","publisher":{"@type":"Organization","name":"Phish Protection","url":"https://phishprotection.com","logo":{"@type":"ImageObject","url":"https://phishprotection.com/images/phishprotection-logo.png"},"description":"Advanced phishing protection and email security for businesses. Real-time threat defense, time-of-click protection, and seamless Office 365 integration.","parentOrganization":{"@type":"Organization","@id":"https://www.wikidata.org/wiki/Q138883901","name":"DuoCircle LLC","url":"https://www.duocircle.com","sameAs":["https://www.wikidata.org/wiki/Q138883901","https://www.crunchbase.com/organization/duocircle-llc","https://www.linkedin.com/company/duocircle","https://github.com/duocircle"],"subOrganization":[{"@type":"Organization","@id":"https://www.wikidata.org/wiki/Q138898167","name":"DMARC Report","url":"https://dmarcreport.com"},{"@type":"Organization","@id":"https://www.wikidata.org/wiki/Q138897474","name":"AutoSPF","url":"https://autospf.com"},{"@type":"Organization","@id":"https://www.wikidata.org/wiki/Q138897912","name":"Phish Protection","url":"https://www.phishprotection.com"}]}}} ``` ```json {"@context":"https://schema.org","@type":"BlogPosting","headline":"Introduction to OpenAPI: 3 Important Security Facts You Need to Know","description":"The OpenAPI specification has grown popular in the past few years especially when it comes to documenting and describing APIs.","url":"https://phishprotection.com/blog/introduction-openapi-3-important-security-facts/","datePublished":"2022-10-25T10:21:52.000Z","dateModified":"2026-04-17T15:43:10.000Z","dateCreated":"2022-10-25T10:21:52.000Z","author":{"@type":"Person","@id":"https://phishprotection.com/authors/brad-slavin/#person","name":"Brad Slavin","url":"https://phishprotection.com/authors/brad-slavin/","jobTitle":"General Manager","description":"Brad Slavin is the founder and General Manager of DuoCircle, the company behind DMARC Report, AutoSPF, Phish Protection, and Mailhop. He founded DuoCircle in 2014 and has led the company's growth to 2,000+ customers across its email security product family. Brad's focus is product strategy, customer relationships, and the commercial and compliance side of email authentication (DPAs, SLAs, enterprise procurement).","image":"https://media.mailhop.org/phishprotection/images/authors/brad-slavin.jpg","knowsAbout":["Email Security Strategy","SaaS Product Management","Enterprise Compliance","Customer Success","Email Deliverability Business"],"worksFor":{"@type":"Organization","name":"Phish Protection","url":"https://phishprotection.com"},"sameAs":["https://www.linkedin.com/in/bradslavin"]},"publisher":{"@type":"Organization","name":"Phish Protection","url":"https://phishprotection.com","logo":{"@type":"ImageObject","url":"https://phishprotection.com/images/phishprotection-logo.png"},"description":"Advanced phishing protection and email security for businesses. Real-time threat defense, time-of-click protection, and seamless Office 365 integration.","parentOrganization":{"@type":"Organization","@id":"https://www.wikidata.org/wiki/Q138883901","name":"DuoCircle LLC","url":"https://www.duocircle.com","sameAs":["https://www.wikidata.org/wiki/Q138883901","https://www.crunchbase.com/organization/duocircle-llc","https://www.linkedin.com/company/duocircle","https://github.com/duocircle"],"subOrganization":[{"@type":"Organization","@id":"https://www.wikidata.org/wiki/Q138898167","name":"DMARC Report","url":"https://dmarcreport.com"},{"@type":"Organization","@id":"https://www.wikidata.org/wiki/Q138897474","name":"AutoSPF","url":"https://autospf.com"},{"@type":"Organization","@id":"https://www.wikidata.org/wiki/Q138897912","name":"Phish Protection","url":"https://www.phishprotection.com"}]},"sameAs":["https://www.linkedin.com/company/duocircle","https://x.com/duocirclellc","https://www.facebook.com/duocirclellc","https://github.com/duocircle"],"contactPoint":{"@type":"ContactPoint","contactType":"customer support","url":"https://phishprotection.com/contact/"},"knowsAbout":["Phishing Protection","Email Security","Anti-Phishing","Business Email Compromise","Ransomware Protection","Time of Click Protection","Office 365 Email Security","Advanced Threat Defense"]},"mainEntityOfPage":{"@type":"WebPage","@id":"https://phishprotection.com/blog/introduction-openapi-3-important-security-facts/"},"articleSection":"intermediate","keywords":"Cybersecurity","wordCount":907,"image":{"@type":"ImageObject","url":"https://media.mailhop.org/phishprotection/images/2022/10/phishing-attack-prevention-7686.jpg","caption":"Phish Protection blog post image","width":1200,"height":630},"speakable":{"@type":"SpeakableSpecification","cssSelector":[".answer-block","h1"]}} ``` ```json {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https://phishprotection.com/"},{"@type":"ListItem","position":2,"name":"Blog","item":"https://phishprotection.com/blog/"},{"@type":"ListItem","position":3,"name":"Intermediate","item":"https://phishprotection.com/intermediate/"},{"@type":"ListItem","position":4,"name":"Introduction to OpenAPI: 3 Important Security Facts You Need to Know","item":"https://phishprotection.com/blog/introduction-openapi-3-important-security-facts/"}]} ```