CORS Credentials Mode — Sending Cookies and Auth Headers Cross-Origin

In this tutorial, you will learn about CORS Credentials Mode. We cover key concepts, practical examples, and best practices to help you master this topic.

CORS credentials mode determines whether the browser includes credentials (cookies, HTTP authentication, client certificates) in cross-origin requests, with specific server requirements for security.

What You'll Learn

• How to include credentials in cross-origin requests
• The credentials option in fetch and XMLHttpRequest
• Server requirements for credential flows

Why It Matters

APIs that rely on cookies or session tokens for authentication must support CORS credentials. Without proper configuration, authenticated users are treated as anonymous.

flowchart LR
    A["fetch(url, {credentials: 'include'})"] --> B["Browser adds\ncookies + auth headers"]
    B --> C["Server checks\nOrigin header"]
    C --> D{"Allow-Credentials:\ntrue?"}
    D -->|"Yes"| E{"Allow-Origin:\nspecific origin?"}
    E -->|"Yes"| F["Response allowed\nwith credentials"]
    D -->|"No"| G["Response blocked"]
    E -->|"No\n(wildcard)"| G
    style C fill:#dbeafe,stroke:#2563eb

Code Examples

// Including credentials in fetch
fetch('https://api.example.com/user/profile', {
  method: 'GET',
  credentials: 'include'  // sends cookies
})
.then(res => res.json())
.then(data => console.log(data));

// Without credentials (default)
fetch('https://api.example.com/user/profile')
  .catch(err => console.log('Not authenticated'));

# Server allowing credentials (Flask)
@app.after_request
def add_cors_headers(response):
    response.headers['Access-Control-Allow-Origin'] = 'https://myapp.com'
    response.headers['Access-Control-Allow-Credentials'] = 'true'
    response.headers['Access-Control-Allow-Methods'] = 'GET, POST'
    response.headers['Access-Control-Allow-Headers'] = 'Content-Type'
    return response

Common Mistakes

1. Using Wildcard Origin with Credentials

Access-Control-Allow-Origin: * is invalid when Allow-Credentials: true. You must specify the exact origin.

2. Forgetting Vary: Origin Header

Cache servers may serve the wrong cached response. Add Vary: Origin to prevent this.

3. Sending Credentials to Wrong Origins

Credentials should only be sent to trusted origins to prevent credential leakage.

4. Ignoring Third-Party Cookie Restrictions

Modern browsers block third-party cookies by default, breaking credential flows.

5. Mixing credentials: 'include' with Access-Control-Allow-Origin: *

The browser rejects the response, making it seem like the server is down.

Practice Questions

1. What is the default credentials value in fetch?
2. Why can't Access-Control-Allow-Origin: * be used with credentials?
3. What does Vary: Origin do in the context of CORS credentials?
4. How do third-party cookie restrictions affect CORS credentials?
5. What are the three values for the credentials option in fetch?

Answers:

1. same-origin — cookies are only sent for same-origin requests.
2. The spec considers wildcards too permissive for credentialed requests.
3. It tells caches to vary responses based on the Origin request header.
4. They prevent cookies from being sent in cross-origin requests, even with CORS.
5. omit (never send), same-origin (only same origin), include (always send).

Challenge: Build a login flow that works across origins: a login page on https://app.example.com authenticates against https://api.example.com using cookies with credentials: 'include'.

FAQ

What's Next

Learn about Wildcard Origins and their limitations, or jump to CORS in Express for practical implementation.