401 Unauthorized: Error Retrieving JWT

Membrane API Gateway returns 401 Unauthorized with a link to this page when the jwtAuth plugin hits an unexpected error while it reads or checks the JWT. The cause is either a malformed token from the client or a gateway that cannot load its keys.

The Error Response

The response contains the status 401 Unauthorized, a detail with the underlying error message, 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.

A request without any token does not produce this error. That case is reported under security/jwt-auth with the detail Could not retrieve JWT.

Common Causes

The Token Is Not Valid Base64URL

The header or payload part of the token contains characters that are not valid Base64URL, for example because it was changed or double-encoded.

The Kid Is Null

The token header contains "kid": null instead of a key ID.

The Keys Could Not Be Loaded

The keys from jwksUris could not be loaded when the request arrived, for example because the identity provider is unreachable, DNS fails, or an outbound proxy blocks the request.

No JWKs Given or None Resolvable

No key is configured for jwtAuth, or none of the configured keys could be resolved.

How to Fix It

1. Client: send the token unmodified, exactly as the identity provider issued it.
2. Operator: check that every URL in jwksUris is reachable from the gateway and returns a valid JWK set, or configure the keys inline.
3. Operator: look for the info-level log line Could not retrieve JWT: ..., which shows the underlying message.

api:
  port: 4000
  flow:
    - jwtAuth:
        expectedAud: order
        jwks:
          jwksUris: https://login.microsoftonline.com/common/discovery/keys
  target:
    url: http://localhost:3000

api:
  port: 4000
  flow:
    - jwtAuth:
        expectedAud: order
        jwks:
          jwksUris: https://login.microsoftonline.com/common/discovery/keys
  target:
    url: http://localhost:3000

You can test from the gateway host whether the JWKS URL is reachable, for example with curl https://login.microsoftonline.com/common/discovery/keys.

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