DEV Community

Alireza Hassankhani
Alireza Hassankhani

Posted on

Understanding the credentials Option in the Fetch API

#webdev #programming #tutorial #security

In the previous article, we learned how credentials: "include" allows the browser to include eligible Cookies in Cross-Origin requests.

However, include is only one of the available credential modes.

In this article, we'll explore all three values of the credentials option, explain their behavior, and see how they relate to Cookies and CORS.

What is the credentials Option?

The credentials option tells the browser whether authentication-related information should be included with an HTTP request.

This includes:

  • Cookies
  • HTTP Authentication credentials
  • TLS Client Certificates

The Fetch API supports three credential modes:

  • omit
  • same-origin
  • include

Each mode behaves differently.

credentials: "omit"

When omit is used, the browser never includes credentials with the request.

fetch("https://api.example.com/profile", {
  credentials: "omit"
})
Enter fullscreen mode Exit fullscreen mode

In this mode:

  • Cookies are never sent.
  • HTTP Authentication credentials are omitted.
  • TLS Client Certificates are not included.

Even if the user is authenticated, the request is treated as anonymous.

This mode is typically used when requesting public resources.

credentials: "same-origin"

This is the default behavior.

If you don't explicitly specify the credentials option, the browser automatically uses:

credentials: "same-origin"
Enter fullscreen mode Exit fullscreen mode

With this mode:

  • Credentials are included only for Same-Origin requests.
  • Credentials are excluded from Cross-Origin requests.

For example, if a request is sent from:

https://app.example.com
Enter fullscreen mode Exit fullscreen mode

to:

https://app.example.com/api
Enter fullscreen mode Exit fullscreen mode

Cookies are included.

However, if the request targets:

https://api.example.com
Enter fullscreen mode Exit fullscreen mode

Cookies are not included because the request is Cross-Origin.

credentials: "include"

The include mode allows the browser to consider credentials even for Cross-Origin requests.

fetch("https://api.example.com/profile", {
  credentials: "include"
})
Enter fullscreen mode Exit fullscreen mode

This does not guarantee that Cookies will be sent.

Instead, the browser evaluates the Cookie based on attributes such as:

  • Domain
  • Path
  • SameSite
  • Secure

Only Cookies that satisfy these rules are included in the request.

Relationship with Cookies

The credentials option directly affects whether Cookies are eligible to be included in a request.

In summary:

  • omit → Never send Cookies.
  • same-origin → Send Cookies only with Same-Origin requests.
  • include → Allow eligible Cookies to be included in Cross-Origin requests.

It's important to remember that include only allows the browser to consider Cookies—it does not force them to be sent.

Relationship with CORS

When using:

credentials: "include"
Enter fullscreen mode Exit fullscreen mode

the server should also return:

Access-Control-Allow-Credentials: true
Enter fullscreen mode Exit fullscreen mode

In addition, the Access-Control-Allow-Origin header must contain the requesting Origin rather than a wildcard (*).

These headers determine whether JavaScript is allowed to access the response.

They do not necessarily determine whether the Cookie is sent.

It's entirely possible for the browser to send a Cookie, for the server to process the request successfully, and yet for JavaScript to be denied access to the response because the CORS policy was not satisfied.

Summary

The Fetch API provides three credential modes:

  • omit — Never send credentials.
  • same-origin — Send credentials only with Same-Origin requests (default).
  • include — Allow eligible credentials to be included in Cross-Origin requests.

Understanding these modes is essential when working with authentication, Cookies, Sessions, and CORS in modern web applications.

Top comments (0)