HTTP Basic Auth¶

Docs: https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Authentication

Warning

HTTP Basic Auth is very insecure. It is better than nothing, but is enough for nearly all real use-cases. Please, consider using JWT Auth instead.

Requiring auth¶

To work with HTTP Basic auth you would need to subclass either HttpBasicSyncAuth or HttpBasicAsyncAuth and override its sync or async (respectively) authenticate method, which will decide whether or not passed username and password are correct.

Here’s how to do it:

auth.py¶

[source]

from typing import Any

from django.conf import settings
from typing_extensions import override

from dmr import Controller
from dmr.endpoint import Endpoint
from dmr.security.http import HttpBasicAsyncAuth
from dmr.serializer import BaseSerializer


class HttpBasicAsync(HttpBasicAsyncAuth):
    @override
    async def authenticate(
        self,
        endpoint: 'Endpoint',
        controller: 'Controller[BaseSerializer]',
        username: str,
        password: str,
    ) -> Any | None:
        # Define `HTTP_BASIC_USERNAME` and `HTTP_BASIC_PASSWORD`
        # in your settings.py file:
        if (
            username == settings.HTTP_BASIC_USERNAME
            and password == settings.HTTP_BASIC_PASSWORD
        ):
            return True
        return None

Let’s say we defined a horribly weak set of username and password: admin / pass. Let’s check that the auth works:

views.py¶

[source]

from typing import TypedDict

from dmr import Body, Controller
from dmr.plugins.pydantic import PydanticSerializer
from examples.auth.http_basic.auth import HttpBasicAsync


class _RequestModel(TypedDict):
    bill: str


class BillController(
    Controller[PydanticSerializer],
):
    auth = (HttpBasicAsync(),)

    async def post(self, parsed_body: Body[_RequestModel]) -> str:
        return f'Processing bill: {parsed_body["bill"]}'

Run result

$ curl http://127.0.0.1:8000/api/username/ -D - -X POST -d '{"bill": "parking"}' -H 'Content-Type: application/json'
HTTP/1.1 401 Unauthorized
date: Sun, 29 Mar 2026 18:52:13 GMT
server: uvicorn
Content-Type: application/json
X-Frame-Options: DENY
Vary: Accept-Language
Content-Language: en
Content-Length: 58
X-Content-Type-Options: nosniff
Referrer-Policy: same-origin
Cross-Origin-Opener-Policy: same-origin

{"detail":[{"msg":"Not authenticated","type":"security"}]}

$ curl http://127.0.0.1:8000/api/username/ -X POST -d '{"bill": "parking"}' -H 'Content-Type: application/json' -H 'Authorization: Basic YWRtaW46cGFzcw=='
"Processing bill: parking"

Any other authentication method will be better than the one above. Consider using JWT Auth instead.

API Reference¶

class dmr.security.http.HttpBasicSyncAuth(*, security_scheme_name: str = 'http_basic', header: str = 'Authorization')[source]¶

Uses HTTP Basic Auth.

Subclass this type to provide actual username/password check according to your needs. This class is used for sync endpoints.

Warning

HTTP Basic Auth is not really secure and should not be used for anything serious. Consider using JWT instead.

async __call__(endpoint: Endpoint, controller: Controller[BaseSerializer]) → Any | None[source]¶: Does the login routine.

abstractmethod async authenticate(endpoint: Endpoint, controller: Controller[BaseSerializer], username: str, password: str) → Any | None[source]¶: Override this method to provide an actual user/password check.

classmethod provide_response_specs(metadata: EndpointMetadata, controller_cls: type[Controller[BaseSerializer]], existing_responses: Mapping[HTTPStatus, ResponseSpec]) → list[ResponseSpec]¶: Provides responses that can happen when user is not authed.

property security_requirement: dict[str, list[str]]¶: Provides a security schema usage requirement.

property security_schemes: dict[str, SecurityScheme | Reference]¶: Provides a security schema definition.

dmr.security.http.basic_auth(username: str, password: str, *, prefix: str = 'Basic ') → str[source]¶

Return a header value for basic auth for a given username and password.

>>> basic_auth('admin', 'pass')
'Basic YWRtaW46cGFzcw=='

>>> basic_auth('admin', 'pass', prefix='')
'YWRtaW46cGFzcw=='