Header Matching

Use headers to match against HTTP request headers. The most common use case is authentication — returning different responses based on the presence and shape of an Authorization header.

Basic shape

{
  "method": "GET",
  "path": "/api/protected",
  "status": 200,
  "headers": {
    "required": {
      "authorization": { "prefix": "Bearer " }
    },
    "forbidden": [],
    "strict": false
  },
  "response": {
    "data": "secret stuff"
  }
}

Three keys at the top of headers:

• required — headers that must be present and match the given pattern.
• forbidden — header names that must not be present.
• strict — if true, the request can have only the listed required headers.

Matching modes for required headers

Each value in required can be one of five matcher types:

Exact match

{ "x-api-key": "abc123" }

The header value must equal exactly that string.

Prefix match

{ "authorization": { "prefix": "Bearer " } }

The header value must start with the given prefix. Ideal for token-style auth where you don’t care about the token value, only its format.

Contains

{ "content-type": { "contains": "json" } }

The header value must contain the given substring. Matches application/json, application/vnd.api+json, etc.

Regex match

{ "x-api-key": { "regex": "^[A-Za-z0-9]{32}$" } }

The header value must match the regex. Use for strict format validation (e.g. exactly 32 alphanumeric characters).

Any value

{ "accept": { "any": null } }

The header must be present, but any value is accepted.

Forbidden headers

Specify headers that must not be present:

{
  "headers": {
    "required": { "authorization": { "prefix": "Bearer " } },
    "forbidden": ["x-debug", "x-internal"]
  }
}

This matches a request with a Bearer token but without any debug or internal headers — useful for simulating production behavior where internal headers would be stripped at a gateway.

Header names are case-insensitive

HTTP header names are case-insensitive per the spec, and Mimic follows this rule. These are all equivalent:

{ "authorization": "..." }
{ "Authorization": "..." }
{ "AUTHORIZATION": "..." }

Header values, however, are case-sensitive. "Bearer abc" and "bearer abc" are different.

Worked example: protected endpoint with two outcomes

You can use two mocks to simulate “authorized” vs “unauthorized” responses for the same endpoint.

mocks/protected_ok.json:

{
  "method": "GET",
  "path": "/api/account",
  "status": 200,
  "headers": {
    "required": { "authorization": { "prefix": "Bearer " } }
  },
  "response": {
    "id": 1,
    "email": "[email protected]"
  }
}

mocks/protected_unauthorized.json:

{
  "method": "GET",
  "path": "/api/account",
  "status": 401,
  "response": {
    "error": "unauthorized",
    "message": "Authorization header required"
  }
}

Now:

# Returns 200 with account data
curl -H "Authorization: Bearer xyz" http://localhost:8080/api/account

# Returns 401
curl http://localhost:8080/api/account

Mimic prefers the more specific mock (the one with the headers matcher) when both could match. See Match Priority for the scoring rules.

Common gotchas

• Header names are case-insensitive, values are not. Don’t lowercase a token value.
• The host and content-length headers are managed by the HTTP client and Mimic itself — matching against them rarely behaves the way you’d expect. Stick to application-level headers.
• Bearer tokens with a trailing space. A common mistake: "prefix": "Bearer" (without the trailing space) will match "Bearertoken" as well. Use "prefix": "Bearer " with the space.