401 Unauthorized: JWT Header Is Not JSON

Membrane API Gateway links to this page when the jwtAuth plugin rejects a token whose header is not valid JSON. The request is answered with 401 Unauthorized in the request flow.

The Error Response

The response contains the status 401 Unauthorized, the problem type https://membrane-api.io/problems/security and a link to this page. The type security means that a security plugin refused access to the API.

What a JWT Looks Like

A JWT consists of three Base64URL-encoded parts separated by dots: header, payload and signature. The decoded header is a JSON object such as {"alg":"RS256","kid":"key-1"}, and the decoded payload is a JSON object with the claims. The jwtAuth plugin decodes both before it verifies the signature.

Common Causes

The Token Was Altered or Truncated

The header part of the token was changed, cut off or copied incompletely, so it no longer decodes to a JSON object.

The Value Is Not a JWT

The client sends some other value with three dot-separated parts in the header the plugin reads, for example a self-built or test token.

How to Fix It

1. Client: send the token exactly as the identity provider issued it.
2. Decode the header and payload of the token, for example with a JWT debugger, and check that both are JSON objects.
3. If the error persists with valid tokens, report it with the log output.

Hide Details in Production

By default, Membrane runs in development mode and adds details to error responses that help you find the problem. These details may reveal information about your setup. In production, turn them off:

configuration:
  production: true

configuration:
  production: true

Add the configuration document to your apis.yaml and separate it from the APIs with ---.

Related Documentation

Configuration reference:

• jwtAuth

Tutorials with runnable examples:

• JWT Signing
• OAuth2 Distributed Validation

← All Membrane error messages