Name: Set-Cookie Analyzer API: Cookie Security Flag Checker
Brand: glowhalo
SKU: api-glowhalo-set-cookie
Availability: InStock
Author: API Market

# Set-Cookie Analyzer API

## Overview

The Set-Cookie Analyzer API checks the cookies a website sets and reports, in JSON, which ones are missing the Secure, HttpOnly or SameSite flags or break the cookie rules in RFC 6265 and the RFC 6265bis draft. The analyze endpoint fetches a URL you give it, follows redirects hop by hop (up to 5), and analyzes every Set-Cookie header from every hop. The parse endpoint runs the same checks on Set-Cookie header text you paste in, offline, with no outbound request, so you can test a header before it ever ships.

It is built for developers, security reviewers and DevOps teams who want to catch cookie misconfigurations from CI or a script. For each cookie you get its attributes (Domain, Path, Expires or Max-Age, Secure, HttpOnly, SameSite, Partitioned, Priority), its `__Host-` or `__Secure-` prefix, its lifetime and size, and a list of coded issues with a severity. Each response also carries an overall grade (A+ to F) and a score out of 100. The grade and score use the provider's own formula; they describe cookie attributes only and are not a security audit of the site or a cookie-consent or privacy-law compliance check. Full cookie values are never returned, only `valueLength` and a short masked `valuePreview` (at most the first 3 characters).

## Features

*   **2 endpoints**: Analyze the cookies a live URL sets, or parse Set-Cookie header text you supply.
*   **Flexible input**: Pass a URL (a value without a scheme, such as `example.com`, is treated as https), a raw header block, or an array of Set-Cookie strings.
*   **Redirect-aware**: Redirects are followed hop by hop (up to 5), and each cookie's `setBy` field shows which hop set it.
*   **Rule checks**: Based on RFC 6265 and the RFC 6265bis draft: SameSite=None needs Secure, `__Host-` and `__Secure-` prefix requirements, the 400-day lifetime cap and the 4096-byte size limit, plus best practices such as flagging session-like cookie names that lack HttpOnly.
*   **Coded findings**: Every finding is an `issues[]` entry with a stable `code` (for example `samesite_none_requires_secure`, `host_prefix_violation`, `httponly_missing`), a severity (error, warning or info) and a message.
*   **Grades and scores**: An A+ to F grade and a 0 to 100 score per cookie and for the whole response, plus counts of errors, warnings and infos.
*   **Masked values**: Cookie values are never returned in full, only their length and a masked preview.
*   **Caching**: Analyze results are cached for 6 hours per URL; add `fresh=1` to bypass the cache.
*   **Rate limit**: 10 requests per second on both the Free and Basic plans.

## Use Cases

*   **CI and release checks**: Fail a pipeline when a session cookie loses Secure, HttpOnly or SameSite after a deploy.
*   **Security reviews**: List the cookies a vendor or partner site sets and how each one is configured.
*   **Debugging**: Paste a raw Set-Cookie header into the parse endpoint and see which rules it breaks before you ship it.
*   **Prefix and cross-site checks**: Confirm that `__Host-` and `__Secure-` cookies meet their requirements and that SameSite=None cookies are also Secure.
*   **Monitoring**: Re-check key pages on a schedule and alert when the grade or the error count changes.

## API Documentation

### Base URL

All requests go through the API.market gateway at this base URL:

```
https://prod.api.market/api/v1/glowhalo/set-cookie
```

### Authentication

Every request needs your API.market key in the `x-api-market-key` header:

```
x-api-market-key: YOUR_API_KEY
```

Replace `YOUR_API_KEY` with your actual API key.

### Endpoints

#### 1. Analyze the Set-Cookie headers of a URL

Sends one anonymous GET to the URL, follows up to 5 redirects hop by hop, and returns a report on every cookie set along the way: attributes, prefix, lifetime, size, coded issues, a grade and a score. It also returns the final URL, the target's HTTP status code and the redirect chain with a cookie count per hop. When the server sends no Set-Cookie headers, `cookieCount` is 0, `grade` is `no_cookies` and `score` is `null`. Results are cached for 6 hours per URL.

**Method:** `GET`

**Endpoint:** `/v1/analyze`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `url` | query | Page to inspect, for example `https://www.amazon.com`. A value without a scheme is treated as https. The aliases `u`, `link`, `target`, `site`, `website`, `domain` and `host` are also accepted. | string | Yes | - | - |
| `fresh` | query | Set to `1` to bypass the 6-hour result cache. | string | No | - | - |

**Example Request:**

```bash
curl -X GET "https://prod.api.market/api/v1/glowhalo/set-cookie/v1/analyze?url=https://www.amazon.com" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK, abridged to 2 of 6 cookies):**

```json
{
  "url": "https://www.amazon.com/",
  "finalUrl": "https://www.amazon.com/",
  "statusCode": 200,
  "redirectChain": [
    {
      "url": "https://www.amazon.com/",
      "statusCode": 200,
      "cookieCount": 6
    }
  ],
  "cookieCount": 6,
  "grade": "B",
  "score": 88,
  "summary": {
    "errors": 0,
    "warnings": 5,
    "infos": 14
  },
  "cookies": [
    {
      "name": "session-id",
      "valueLength": 19,
      "valuePreview": "137…",
      "attributes": {
        "domain": ".amazon.com",
        "path": "/",
        "expires": "2027-10-13T08:32:09.000Z",
        "maxAge": null,
        "secure": true,
        "httpOnly": false,
        "sameSite": null,
        "partitioned": false,
        "priority": null
      },
      "prefix": null,
      "lifetime": {
        "type": "persistent",
        "seconds": 31535999,
        "source": "expires"
      },
      "deletion": false,
      "sizeBytes": 29,
      "issues": [
        {
          "severity": "info",
          "code": "domain_leading_dot",
          "message": "A leading dot in Domain is ignored by modern browsers (RFC 6265 section 5.2.3); it can be removed."
        },
        {
          "severity": "warning",
          "code": "httponly_missing",
          "message": "The cookie name looks like a session, token or CSRF cookie but lacks HttpOnly, so any script on the page (e.g. via XSS) can read it."
        },
        {
          "severity": "info",
          "code": "samesite_missing",
          "message": "No SameSite attribute: browsers default to Lax (Chrome, Edge, Firefox in some modes). State the intent explicitly with SameSite=Lax, Strict or None."
        }
      ],
      "score": 88,
      "grade": "B",
      "setBy": {
        "hop": 1,
        "url": "https://www.amazon.com/",
        "statusCode": 200
      }
    },
    {
      "name": "sst-main",
      "valueLength": 265,
      "valuePreview": "Sst…",
      "attributes": {
        "domain": ".amazon.com",
        "path": "/",
        "expires": "2027-10-13T08:32:09.000Z",
        "maxAge": null,
        "secure": true,
        "httpOnly": true,
        "sameSite": "Lax",
        "partitioned": false,
        "priority": null
      },
      "prefix": null,
      "lifetime": {
        "type": "persistent",
        "seconds": 31535999,
        "source": "expires"
      },
      "deletion": false,
      "sizeBytes": 273,
      "issues": [
        {
          "severity": "info",
          "code": "domain_leading_dot",
          "message": "A leading dot in Domain is ignored by modern browsers (RFC 6265 section 5.2.3); it can be removed."
        }
      ],
      "score": 99,
      "grade": "A+",
      "setBy": {
        "hop": 1,
        "url": "https://www.amazon.com/",
        "statusCode": 200
      }
    }
  ],
  "cached": false,
  "checkedAt": "2026-10-13T08:32:09.897Z"
}
```

#### 2. Parse pasted Set-Cookie header text

Runs the same checks on Set-Cookie headers you provide and makes no outbound request. Send either `headers` (a raw header block, one Set-Cookie per line; other header lines are ignored) or `setCookie` (an array with one string per cookie). The response has the same per-cookie report as analyze, plus an `assumptions` object that states whether HTTPS was assumed and which host was used.

**Method:** `POST`

**Endpoint:** `/v1/parse`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `headers` | body | Raw header lines, newline separated, for example `Set-Cookie: a=b; Secure`. Required unless `setCookie` is sent. | string | No | - | 50 cookies, 8 KB each |
| `setCookie` | body | Alternative to `headers`: an array with one Set-Cookie string per cookie. | array of strings | No | - | 50 cookies, 8 KB each |
| `host` | body | Request host, for example `www.example.com`. Enables the Domain-mismatch check. | string | No | - | - |
| `https` | body | Whether the cookies were served over HTTPS. Controls the Secure-missing check. | boolean | No | `true` | - |

**Example Request:**

```bash
curl -X POST "https://prod.api.market/api/v1/glowhalo/set-cookie/v1/parse" \
  -H "x-api-market-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"headers":"Set-Cookie: __Host-id=1; Domain=a.com\nSet-Cookie: s=1; SameSite=None"}'
```

**Example Response (200 OK):**

```json
{
  "cookieCount": 2,
  "grade": "D",
  "score": 63,
  "summary": {
    "errors": 2,
    "warnings": 2,
    "infos": 3
  },
  "assumptions": {
    "https": true,
    "host": null,
    "note": "Parsed offline. Secure checks assume the cookie was served over HTTPS (set \"https\": false to change); Domain checks run only when \"host\" is given."
  },
  "cookies": [
    {
      "name": "__Host-id",
      "valueLength": 1,
      "valuePreview": "…",
      "attributes": {
        "domain": "a.com",
        "path": null,
        "expires": null,
        "maxAge": null,
        "secure": false,
        "httpOnly": false,
        "sameSite": null,
        "partitioned": false,
        "priority": null
      },
      "prefix": "__Host-",
      "lifetime": {
        "type": "session",
        "seconds": null,
        "source": null
      },
      "deletion": false,
      "sizeBytes": 10,
      "issues": [
        {
          "severity": "error",
          "code": "host_prefix_violation",
          "message": "A __Host- cookie requires the Secure attribute, Path=/, no Domain attribute (RFC 6265bis section 4.1.3.2); browsers reject it otherwise."
        },
        {
          "severity": "warning",
          "code": "secure_missing",
          "message": "The cookie has no Secure attribute although it was served over HTTPS, so browsers may also send it over plain HTTP."
        },
        {
          "severity": "info",
          "code": "httponly_missing",
          "message": "The cookie has no HttpOnly attribute, so scripts can read it. Fine if JavaScript needs it; otherwise add HttpOnly."
        },
        {
          "severity": "info",
          "code": "samesite_missing",
          "message": "No SameSite attribute: browsers default to Lax (Chrome, Edge, Firefox in some modes). State the intent explicitly with SameSite=Lax, Strict or None."
        }
      ],
      "score": 63,
      "grade": "D"
    },
    {
      "name": "s",
      "valueLength": 1,
      "valuePreview": "…",
      "attributes": {
        "domain": null,
        "path": null,
        "expires": null,
        "maxAge": null,
        "secure": false,
        "httpOnly": false,
        "sameSite": "None",
        "partitioned": false,
        "priority": null
      },
      "prefix": null,
      "lifetime": {
        "type": "session",
        "seconds": null,
        "source": null
      },
      "deletion": false,
      "sizeBytes": 2,
      "issues": [
        {
          "severity": "error",
          "code": "samesite_none_requires_secure",
          "message": "SameSite=None requires the Secure attribute; Chrome, Firefox and Safari reject the cookie otherwise (RFC 6265bis section 4.1.2.7)."
        },
        {
          "severity": "warning",
          "code": "secure_missing",
          "message": "The cookie has no Secure attribute although it was served over HTTPS, so browsers may also send it over plain HTTP."
        },
        {
          "severity": "info",
          "code": "httponly_missing",
          "message": "The cookie has no HttpOnly attribute, so scripts can read it. Fine if JavaScript needs it; otherwise add HttpOnly."
        }
      ],
      "score": 64,
      "grade": "D"
    }
  ],
  "checkedAt": "2026-10-13T08:30:51.246Z"
}
```

## Status Codes

| Code | Status | Description |
|---|---|---|
| 200 | OK | The report is in the response body. For analyze, the target site's own HTTP status is reported in `statusCode`, so a 200 from this API can still describe a page that answered 403 or 429. |
| 400 | Bad Request | The `url` parameter or the parse body is missing or invalid, or the target is a private-network address. The body carries an error code and message. |
| 401 | Unauthorized | The `x-api-market-key` value is invalid or expired. |
| 403 | Forbidden | Your subscription does not include this endpoint. |
| 404 | Not Found | The endpoint path does not exist. Check the path against this page. |
| 413 | Payload Too Large | The parse request exceeds the limit of 50 cookies or 8 KB per cookie. |
| 429 | Too Many Requests | You went over 10 requests per second or used up your plan's request quota. |
| 500 | Internal Server Error | Something failed while processing the request. Retry after a short delay. |
| 502 | Bad Gateway | Analyze could not fetch the target URL. |
| 504 | Gateway Timeout | The target URL did not respond in time. |

## Rate Limits

Both plans allow 10 requests per second: the Free plan (500 requests per month) and the Basic plan (25,000 requests per month). Both quotas are hard limits. Requests above the per-second limit, or after the monthly quota is used up, return `429 Too Many Requests`; back off before retrying and honour any `Retry-After` header. Analyze results are cached for 6 hours per URL, so repeated checks of the same page within that window return the cached report; use `fresh=1` only when you need a new fetch, for example right after a deploy.

## FAQ

**Does the API return my cookie values?**

No. Full cookie values are never returned. Each cookie has a `valueLength` and a masked `valuePreview` that shows at most the first 3 characters.

**Why does analyze show fewer cookies than my browser does?**

Analyze makes a single anonymous GET from the provider's servers. Cookies set by JavaScript, or only after login or consent, are not visible, and sites that block datacenter traffic may show fewer cookies or none.

**What if the target site blocks or rate-limits the check?**

The target site's own HTTP status code is reported in `statusCode` and in `redirectChain`. If it answers with something like 429, the response has `cookieCount` 0, `grade` `no_cookies` and a `note` explaining that the site's normal cookies may not be visible. Retry later with `fresh=1`.

**What do the grade and score mean?**

They summarize the cookie attributes using the provider's own formula: A+ to F and 0 to 100, per cookie and overall. They are not a security audit of the site or a cookie-consent or privacy-law compliance check.

**How do I check a header before it is deployed?**

Send it to `POST /v1/parse` in `headers` or `setCookie`. No request is made to any site. Pass `host` to enable the Domain-mismatch check, and set `https` to `false` if the cookie is served over plain HTTP.

**How fresh are analyze results?**

Results are cached for 6 hours per URL, and the `cached` field tells you whether the response came from the cache. Add `fresh=1` to force a new fetch.

**Can I check internal or staging hosts?**

Only if they are reachable from the public internet. Private-network targets are rejected. For anything else, copy the Set-Cookie headers and use the parse endpoint.

## Contact Us

If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.


Set-Cookie analyzer API: check a URL's cookies for Secure, HttpOnly, SameSite, prefix and lifetime issues. Coded JSON issues and an A+ to F grade.

Set-Cookie Analyzer API: Cookie Security Flag Checker