APIKeyCookie Class — fastapi Architecture

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

Class python Security

Entity Profile

Security→ APIKeyCookie Class — fastapi Architecture

Dependency Diagram

graph TD
  102827f4_bb2e_ec6a_78ac_f97742d3df84["APIKeyCookie"]
  f01173ae_dbd6_605b_f92e_0035a743c419["APIKeyBase"]
  102827f4_bb2e_ec6a_78ac_f97742d3df84 -->|extends| f01173ae_dbd6_605b_f92e_0035a743c419
  fac63c1f_ae18_a88d_487c_0fd6cfe587f0["api_key.py"]
  102827f4_bb2e_ec6a_78ac_f97742d3df84 -->|defined in| fac63c1f_ae18_a88d_487c_0fd6cfe587f0
  5655dd4c_b4d9_2c34_bb37_357629c6fa36["__init__()"]
  102827f4_bb2e_ec6a_78ac_f97742d3df84 -->|method| 5655dd4c_b4d9_2c34_bb37_357629c6fa36
  83e91930_3a1c_6c0c_1c63_147bbf77b910["__call__()"]
  102827f4_bb2e_ec6a_78ac_f97742d3df84 -->|method| 83e91930_3a1c_6c0c_1c63_147bbf77b910

Relationship Graph

Source Code

fastapi/security/api_key.py lines 233–318

class APIKeyCookie(APIKeyBase):
    """
    API key authentication using a cookie.

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

    ## 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 APIKeyCookie

    app = FastAPI()

    cookie_scheme = APIKeyCookie(name="session")


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

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

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