APIKeyHeader Class — fastapi Architecture

Architecture documentation for the APIKeyHeader class in api_key.py from the fastapi codebase.

Class python Security

Entity Profile

Security→ APIKeyHeader Class — fastapi Architecture

Dependency Diagram

graph TD
  ab402c28_d154_c88d_9709_5fae7c878ce8["APIKeyHeader"]
  f01173ae_dbd6_605b_f92e_0035a743c419["APIKeyBase"]
  ab402c28_d154_c88d_9709_5fae7c878ce8 -->|extends| f01173ae_dbd6_605b_f92e_0035a743c419
  fac63c1f_ae18_a88d_487c_0fd6cfe587f0["api_key.py"]
  ab402c28_d154_c88d_9709_5fae7c878ce8 -->|defined in| fac63c1f_ae18_a88d_487c_0fd6cfe587f0
  ccc39d3a_d284_3045_4a6c_2ab64b4b3256["__init__()"]
  ab402c28_d154_c88d_9709_5fae7c878ce8 -->|method| ccc39d3a_d284_3045_4a6c_2ab64b4b3256
  a4452985_9360_8685_8df8_22f6ddbc1b50["__call__()"]
  ab402c28_d154_c88d_9709_5fae7c878ce8 -->|method| a4452985_9360_8685_8df8_22f6ddbc1b50

Relationship Graph

Source Code

fastapi/security/api_key.py lines 145–230

class APIKeyHeader(APIKeyBase):
    """
    API key authentication using a header.

    This defines the name of the header that should be provided in the request with
    the API key and integrates that into the OpenAPI documentation. It extracts
    the key value sent in the header automatically and provides it as the dependency
    result. But it doesn't define how to send that key to the client.

    ## Usage

    Create an instance object and use that object as the dependency in `Depends()`.

    The dependency result will be a string containing the key value.

    ## Example

    ```python
    from fastapi import Depends, FastAPI
    from fastapi.security import APIKeyHeader

    app = FastAPI()

    header_scheme = APIKeyHeader(name="x-key")


    @app.get("/items/")
    async def read_items(key: str = Depends(header_scheme)):
        return {"key": key}
    ```
    """

    def __init__(
        self,
        *,
        name: Annotated[str, Doc("Header name.")],
        scheme_name: Annotated[
            Optional[str],
            Doc(
                """
                Security scheme name.

                It will be included in the generated OpenAPI (e.g. visible at `/docs`).
                """
            ),
        ] = None,
        description: Annotated[
            Optional[str],
            Doc(
                """
                Security scheme description.

                It will be included in the generated OpenAPI (e.g. visible at `/docs`).
                """
            ),
        ] = None,
        auto_error: Annotated[
            bool,
            Doc(
                """
                By default, if the header is not provided, `APIKeyHeader` will
                automatically cancel the request and send the client an error.

                If `auto_error` is set to `False`, when the header is not available,
                instead of erroring out, the dependency result will be `None`.

                This is useful when you want to have optional authentication.

                It is also useful when you want to have authentication that can be
                provided in one of multiple optional ways (for example, in a header or
                in an HTTP Bearer token).
                """
            ),
        ] = True,
    ):
        super().__init__(
            location=APIKeyIn.header,
            name=name,
            scheme_name=scheme_name,
            description=description,
            auto_error=auto_error,