APIKeyQuery Class — fastapi Architecture

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

Class python Security

Entity Profile

Security→ APIKeyQuery Class — fastapi Architecture

Dependency Diagram

graph TD
  2c7ee275_5b1d_2ff3_f026_73e1cfeec40b["APIKeyQuery"]
  f01173ae_dbd6_605b_f92e_0035a743c419["APIKeyBase"]
  2c7ee275_5b1d_2ff3_f026_73e1cfeec40b -->|extends| f01173ae_dbd6_605b_f92e_0035a743c419
  fac63c1f_ae18_a88d_487c_0fd6cfe587f0["api_key.py"]
  2c7ee275_5b1d_2ff3_f026_73e1cfeec40b -->|defined in| fac63c1f_ae18_a88d_487c_0fd6cfe587f0
  f0875812_eebe_7a79_1faf_6af811129326["__init__()"]
  2c7ee275_5b1d_2ff3_f026_73e1cfeec40b -->|method| f0875812_eebe_7a79_1faf_6af811129326
  ec60d565_1480_f71a_0040_d5437d343db3["__call__()"]
  2c7ee275_5b1d_2ff3_f026_73e1cfeec40b -->|method| ec60d565_1480_f71a_0040_d5437d343db3

Relationship Graph

Source Code

fastapi/security/api_key.py lines 53–142

class APIKeyQuery(APIKeyBase):
    """
    API key authentication using a query parameter.

    This defines the name of the query parameter 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 query parameter automatically and provides it as the
    dependency result. But it doesn't define how to send that API 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 APIKeyQuery

    app = FastAPI()

    query_scheme = APIKeyQuery(name="api_key")


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

    def __init__(
        self,
        *,
        name: Annotated[
            str,
            Doc("Query parameter 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 query parameter is not provided, `APIKeyQuery` will
                automatically cancel the request and send the client an error.

                If `auto_error` is set to `False`, when the query parameter 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 query
                parameter or in an HTTP Bearer token).
                """
            ),
        ] = True,
    ):
        super().__init__(
            location=APIKeyIn.query,