401 Unauthorized or 403 Forbidden: API Key Rejected

Membrane API Gateway returns 401 Unauthorized or 403 Forbidden with a link to this page when the apiKey plugin rejects a request in the request flow. The request either carries no API key, or the key is not known to any of the configured key stores.

The Error Response

The response contains the status 401 or 403, a detail that tells the two cases apart, the problem type https://membrane-api.io/problems/security/authorization-denied and a link to this page. The type security with the subtype authorization-denied means that a security plugin refused access to the API.

How the API Key Plugin Works

The apiKey plugin reads the key from the request with its extractors. The first extractor that finds a key wins. Without extractors, the key is read from the X-Api-Key header. The key is then looked up in the configured stores, for example a simple list, an apiKeyFileStore, a databaseApiKeyStore or a mongoDBApiKeyStore.

api:
  port: 2000
  flow:
    - apiKey:
        stores:
          - simple:
              - secret:
                  value: aed8bcc4-7c83-44d5-8789-21e4024ac873
        extractors:
          - header: X-Api-Key
  target:
    url: https://api.predic8.de

api:
  port: 2000
  flow:
    - apiKey:
        stores:
          - simple:
              - secret:
                  value: aed8bcc4-7c83-44d5-8789-21e4024ac873
        extractors:
          - header: X-Api-Key
  target:
    url: https://api.predic8.de

Common Causes

401: The Request Has No Key

The request carries no key where the extractors look for one. A common mistake is sending the key in a different header or as a query parameter while the plugin only reads the X-Api-Key header.

403: The Key Is Unknown

The key was found in the request, but none of the configured stores contains it. Check for typos, whitespace and keys that were removed from the store.

403: No Key Store Is Configured

Without at least one store next to the apiKey plugin, no key can be found, so every request with a key is rejected.

403: A Key Store Failed

If a store fails while it looks up the key, for example because the database is unreachable or the key file cannot be read, the error is ignored and the key counts as not found. If valid keys are suddenly rejected, check the store.

How to Fix It

1. Client: send a valid key in the header or query parameter the API expects, by default X-Api-Key.
2. Operator: check that the key is in one of the stores, and that at least one store is configured.
3. Operator: if keys suddenly become invalid, check that the database or file behind the key store is reachable.

To let requests without a valid key pass while still extracting keys and scopes, set required: false:

api:
  port: 2000
  flow:
    - apiKey:
        required: false
        stores:
          - simple:
              - secret:
                  value: aed8bcc4-7c83-44d5-8789-21e4024ac873
  target:
    url: https://api.predic8.de

api:
  port: 2000
  flow:
    - apiKey:
        required: false
        stores:
          - simple:
              - secret:
                  value: aed8bcc4-7c83-44d5-8789-21e4024ac873
  target:
    url: https://api.predic8.de

Details in Production Mode

Unlike most errors, the details and the link to this page are sent for this error even when Membrane runs in production mode. Setting production: true in the configuration document does not remove them. The detail only states whether the key was missing or invalid and does not reveal the configured keys.

Related Documentation

Configuration reference:

• apiKey

Tutorials with runnable examples:

• API Key Simple
• API Key RBAC

← All Membrane error messages