> For the complete documentation index, see [llms.txt](https://eazyapi-1.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://eazyapi-1.gitbook.io/docs/open-api-guide/authentication/api-keys.md).

# API Keys

Some APIs use API keys for authorization. An API key is a token that a client provides when making API calls. The key can be sent in the query string:

{% code lineNumbers="true" %}

```yaml
GET /something?api_key=abcdef12345
```

{% endcode %}

or as a request header:

{% code lineNumbers="true" %}

```yaml
GET /something HTTP/1.1
X-API-Key: abcdef12345
```

{% endcode %}

or as a [cookie](/docs/open-api-guide/authentication/cookie-authentication.md):

{% code lineNumbers="true" %}

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

{% endcode %}

API keys are supposed to be a secret that only the client and server know. Like [Basic authentication](/docs/open-api-guide/authentication/basic-authentication.md), API key-based authentication is only considered secure if used together with other security mechanisms such as HTTPS/SSL.

### Describing API Keys

In OpenAPI 3.0, API keys are described as follows:

{% code lineNumbers="true" %}

```yaml
openapi: 3.0.0
...
# 1) Define the key name and location
components:
  securitySchemes:
    ApiKeyAuth:        # arbitrary name for the security scheme
      type: apiKey
      in: header       # can be "header", "query" or "cookie"
      name: X-API-KEY  # name of the header, query parameter or cookie
# 2) Apply the API key globally to all operations
security:
  - ApiKeyAuth: []     # use the same name as under securitySchemes
```

{% endcode %}

This example defines an API key named `X-API-Key` sent as a request header `X-API-Key: <key>`. The key name *ApiKeyAuth* is an arbitrary name for the security scheme (not to be confused with the API key name, which is specified by the `name` key). The name *ApiKeyAuth* is used again in the `security` section to apply this security scheme to the API. **Note:** The `securitySchemes` section alone is not enough; you must also use `security` for the API key to have effect. `security` can also be set on the operation level instead of globally. This is useful if just a subset of the operations need the API key:

{% code lineNumbers="true" %}

```yaml
paths:
  /something:
    get:
      # Operation-specific security:
      security:
        - ApiKeyAuth: []
      responses:
        '200':
          description: OK (successfully authenticated)
```

{% endcode %}

Note that it is possible to support multiple authorization types in an API. See [Using Multiple Authentication Types](/docs/open-api-guide/authentication.md#multiple).

### Multiple API Keys <a href="#multiple" id="multiple"></a>

Some APIs use a pair of security keys, say, API Key and App ID. To specify that the keys are used together (as in logical AND), list them in the same array item in the `security` array:

{% code lineNumbers="true" %}

```yaml
components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-API-KEY
    appId:
      type: apiKey
      in: header
      name: X-APP-ID
security:
  - apiKey: []
    appId:  []   # <-- no leading dash (-)
```

{% endcode %}

Note the difference from:

{% code lineNumbers="true" %}

```yaml
security:
  - apiKey: []
  - appId:  []
```

{% endcode %}

which means either key can be used (as in logical OR). For more examples, see [Using Multiple Authentication Types](/docs/open-api-guide/authentication.md#multiple).

### 401 Response <a href="#response" id="response"></a>

You can define the 401 “Unauthorized” response returned for requests with missing or invalid API key. This response includes the `WWW-Authenticate` header, which you may want to mention. As with other common responses, the 401 response can be defined in the global `components/responses` section and referenced elsewhere via `$ref`.

{% code lineNumbers="true" %}

```yaml
aths:
  /something:
    get:
      ...
      responses:
        ...
        '401':
           $ref: "#/components/responses/UnauthorizedError"
    post:
      ...
      responses:
        ...
        '401':
          $ref: "#/components/responses/UnauthorizedError"
components:
  responses:
    UnauthorizedError:
      description: API key is missing or invalid
      headers:
        WWW_Authenticate:
          schema:
            type: string
```

{% endcode %}

To learn more about describing responses, see [Describing Responses](/docs/open-api-guide/describing-responses.md).