# API Key in OpenAPI

# The API Key security scheme in OpenAPI

An API Key security scheme is the most common form of authentication for machine-to-machine APIs. It supports passing a pre-shared secret via the Authorization header (or another custom header), via a cookie,  or as a query parameter.

The following examples demonstrate the three methods for passing an API key.

- As a query string:

    ```http
    GET /drinks?api_key=abcdef12345
    ```

- As a request header:

    ```http
    GET /something HTTP/1.1
    
    Speakeasy-API-Key: abcdef12345
    ```

- As a cookie:

    ```http
    GET /something HTTP/1.1
    
    Cookie: X-API-KEY=abcdef12345
    ```

Although the API Key security scheme is one of the most commonly used mechanisms, its security depends on the type of key used and how it was generated. Passing an API key via a header or cookie is often more secure than passing it via a query parameter, because logging mechanisms often store query param information.

The biggest security flaw is that most preshared secrets are long-lived, and if intercepted, can be used until they expire (generally in months or years) or are revoked. This risk is usually tolerated for machine-to-machine applications, as the chance of interception (especially when using private VPCs/TLS and other mechanisms) is relatively low compared to that of a key from a user's device traveling on a public network.

Regardless of which method you use, using HTTPS or TLS is highly recommended.

## Defining the API Key security scheme

The fields for an API Key security scheme are as follows:

To describe an API key, first create an object in `securitySchemes` with a name of your choosing. You can use `ApiKey` or even `anythingYOULikeAuth`, as long as it's easy to remember and a valid YAML string. Then, define the object `type` as `apiKey` and define the name of the header, query, or cookie parameter as it should appear in the HTTP request:

```yaml
components:
  securitySchemes:
    ApiKey:
      type: apiKey
      name: Speakeasy-API-Key
      in: header
security:
  - ApiKey: []
```

You can add a description to let API users know where to find an API key or which email address to contact to request one.

## Using multiple API keys

Some APIs require two API keys to be used at once. For example, users may need to use an app ID and an app key simultaneously. In such cases, define both keys as `securitySchemes`, then reference them both in the same [Security Requirement Object](/openapi/security).

```yaml
security:
  - AppId: []
    AppKey: [] # no leading dash
components:
  securitySchemes:
    AppId:
      type: apiKey
      name: Speakeasy-App-Id
      in: header
    AppKey:
      type: apiKey
      name: Speakeasy-App-Key
      in: header
```