# Here we are describing the Global security schemes used by the operations in this document
Source: https://speakeasy.com/blog/openapi-tips-auth

import { Callout } from "@/mdx/components";

<Callout title="Announcing: OpenAPI Reference" type="default">
Hi! These blog posts have been popular, so we've built an entire [OpenAPI Reference Guide](/openapi/) to answer any question you have.

It includes detailed information on [**API authentication**](/openapi/security).

Happy Spec Writing!

</Callout>

## The Problem

The OpenAPI spec is best known for descriptions of RESTful APIs, but it's designed to be capable of describing any HTTP API whether that be REST or something more akin to RPC based calls. That leads to the spec having a lot of flexibility baked-in; there's a lot of ways to achieve the exact same result that are equally valid in the eyes of the spec. Because of this, [the OpenAPI](https://spec.openapis.org/oas/v3.1.0#operation-object) documentation is very ambiguous when it comes to how you should define your API. That's why we'd like to take the time to eliminate some of the most common ambiguities that you'll encounter when you build your OpenAPI spec. In this case we'll be taking a look at **how to correctly configure auth in your OpenAPI spec.**

## What Authentication mechanisms are available?

OpenAPI supports a number of different options for API authentication, which can be daunting when first starting out. Before we give our thoughts on the different methods, it's worth highlighting that regardless of the method of authentication you choose, you should pair it with TLS. TLS encrypts the messages to and from your API, to protect you and your users from attack. [Learn more about setting up TLS here](https://letsencrypt.org/getting-started/). Some of the common types of authentication are listed below:

- **apiKey**: This is the most common form of authentication for machine-to-machine (M2M) APIs and supports passing a pre-shared secret in a number of different ways i.e. either via the _Authorization_ header (or another custom header), as a query parameter, or via a cookie. While this is probably the most commonly used mechanism, it is generally one of the least secure. This is especially true if the key is passed outside of headers or cookies (i.e. via query params as various logging mechanisms normally store query param information). The biggest security flaw is that most pre-shared secrets are long lived and if intercepted can be used until they are either revoked or expire (generally in a number of months or years). This risk is normally tolerated for M2M applications as the chance of interception (especially when using private VPCs/TLS and other mechanisms) is relatively low when compared to a key from a user's device traveling on a public network.
- **basic**: This is a simple authentication mechanism baked into the HTTP protocol. It supports sending an _Authorization_ header containing an encoded username and password. While this can be a relatively simple mechanism to get started with, if used incorrectly can risk leaking easy to decode passwords. It also shares a lot of the downsides of apiKeys below.
- **bearer**: This scheme allows the passing of a token (most commonly a JWT) in the _Authorization_ header. This is generally used for short lived tokens that are granted to the users of your API through an additional login mechanism. Using a JWT allows for the storage of additional metadata within the token which can be helpful for some use cases, such as storing scopes for permissions models.
- **oauth2**: A popular open authentication mechanism that supports an authentication flow that allows servers to authenticate on behalf of a user or organization. While more generally used for authenticating clients and end-users it is quite often used in machine-to-machine applications as well, but is less popular due to the added complexity of the authentication flows. OAuth2 is considered more secure than other mechanisms due to its granted privileges through short lived tokens, that limit damage from intercepting the tokens.
- **openIdConnect**: Is an authentication mechanism built on top of OAuth2 that allows obtaining identity information about the authenticating user via JWTs.

## Global Authentication vs Endpoint Authentication

The OpenAPI specification allows you to describe all the above authentication mechanisms and more from the [HTTP Authentication Scheme Registry](https://www.iana.org/assignments/http-authschemes/http-authschemes.xhtml).

Describing security in your OpenAPI document is then done through 1 of 2 different options:

- **Global security**: the security you describe is available for all operations in your document.
- **Per operation security:** when described it overrides any global level security described.

Here is an example of describing security in the ways mentioned above:

```yaml
openapi: 3.0.3
info:
  title: Example Security Definitions
  version: 1.0.0
servers:
  - url: http://api.prod.speakeasy.com