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
Cookie header in all subsequent requests to the server.
- On the logout operation, the server sends back the
Set-Cookie header that causes the cookie to expire.
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
. For example, authentication via a cookie named
is defined as follows:
# 1) Define the cookie name
cookieAuth: # arbitrary name for the security scheme; will be used in the "security" key later
name: JSESSIONID # cookie name
# 2) Apply cookie auth globally to all operations
- cookieAuth: 
In this example, cookie authentication is applied globally to the whole API using the
key at the root level of the specification.
If cookies are required for just a subset of operations, apply
on the operation level instead of doing it globally:
- cookieAuth: 
description: Returns a list of users.
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
header. You can include this information in the
, and also define the
header in the response
, like so:
summary: Logs in and returns the authentication cookie
description: A JSON object containing the login and password.
security:  # no authentication
The session ID is returned in a cookie named `JSESSIONID`. You need to include this cookie in subsequent requests.
example: JSESSIONID=abcde12345; Path=/; HttpOnly
Note that the
are not connected in any way, and the
definition is for documentation purposes only.