OAS 3 This page applies to OpenAPI 3 – the latest version of the OpenAPI Specification.
Cookie authentication uses HTTP cookies to authenticate client requests and maintain session information. It works as follows:
- The client sends a login request to the server.
- On the successful login, the server response includes the Set-Cookie header that contains the cookie name, value, expiry time and some other info. Here is an example that sets the cookie named
Set-Cookie: JSESSIONID=abcde12345; Path=/; HttpOnly
- The client needs to send this cookie in the
Cookieheader in all subsequent requests to the server.
- On the logout operation, the server sends back the
Set-Cookieheader that causes the cookie to expire.
Note: Cookie authentication is vulnerable to Cross-Site Request Forgeries (CSRF) attacks, so it should be used together with other security measures, such as CSRF tokens.
Describing Cookie Authentication
In OpenAPI 3.0 terms, cookie authentication is an API key that is sent
in: cookie. For example, authentication via a cookie named
JSESSIONID is defined as follows:
openapi: 3.0.0 ... # 1) Define the cookie name components: securitySchemes: cookieAuth: # arbitrary name for the security scheme; will be used in the "security" key later type: apiKey in: cookie name: JSESSIONID # cookie name # 2) Apply cookie auth globally to all operations security: - cookieAuth: 
In this example, cookie authentication is applied globally to the whole API using the
security key at the root level of the specification.
If cookies are required for just a subset of operations, apply
security on the operation level instead of doing it globally:
paths: /users: get: security: - cookieAuth:  description: Returns a list of users. responses: '200': description: OK
Cookie authentication can be combined with other authentication methods as explained in Using Multiple Authentication Types.
Describing the Set-Cookie Header
You may also want to document that your login operation returns the cookie in the
Set-Cookie header. You can include this information in the
description, and also define the
Set-Cookie header in the response
headers, like so:
paths: /login: post: summary: Logs in and returns the authentication cookie requestBody: required: true description: A JSON object containing the login and password. content: application/json: schema: $ref: '#/components/schemas/LoginRequest' security:  # no authentication responses: '200': description: > Successfully authenticated. The session ID is returned in a cookie named `JSESSIONID`. You need to include this cookie in subsequent requests. headers: Set-Cookie: schema: type: string example: JSESSIONID=abcde12345; Path=/; HttpOnly
Note that the
Set-Cookie header and
securitySchemes are not connected in any way, and the
Set-Header definition is for documentation purposes only.