Endpoints¶

Endpoints are provided for session login and logout. They are designed to integrate with an ASGI app, such as Starlette or FastAPI.

session_login¶

An endpoint for creating a user session. If you send a GET request to this endpoint, a simple login form is rendered, where a user can manually login.

Hint

You can use a custom login template, which matches the look and feel of your application. See the template_path parameter.

Alternatively, you can login programatically by sending a POST request to this endpoint (passing in username and password parameters as JSON, or as form data).

When login is successful, the user is redirected. The destination can be configured using the redirect_to parameter.

Additional security¶

It’s recommended to protect any login endpoints with rate limiting middleware, to help slow down any brute force attacks.

You can also add a CAPTCHA if you prefer. The approach is very similar to the register endpoint.

Examples¶

Here’s a Starlette example:

from piccolo_api.session_auth.endpoints import session_login
from starlette import Starlette

app = Starlette()

app.mount('/login/', session_login())

Here’s a FastAPI example:

from piccolo_api.session_auth.endpoints import session_login
from fastapi import FastAPI

app = FastAPI()

app.mount('/login/', session_login())

Source¶

piccolo_api.session_auth.endpoints.session_login(auth_table: t.Type[BaseUser] = BaseUser, session_table: t.Type[SessionsBase] = SessionsBase, session_expiry: timedelta = timedelta(hours=1), max_session_expiry: timedelta = timedelta(days=7), redirect_to: t.Optional[str] = '/', production: bool = False, cookie_name: str = 'id', template_path: t.Optional[str] = None, hooks: t.Optional[LoginHooks] = None, captcha: t.Optional[Captcha] = None, styles: t.Optional[Styles] = None) → t.Type[SessionLoginEndpoint][source]¶

An endpoint for creating a user session.

Parameters:

auth_table – Which table to authenticate the username and password with. It defaults to BaseUser.
session_table – Which table to store the session in. If defaults to SessionsBase.
session_expiry – How long the session will last.
max_session_expiry – If the session is refreshed (see the increase_expiry parameter for SessionsAuthBackend), it can only be refreshed up to a certain limit, after which the session is void.
redirect_to – Where to redirect to after successful login.
production – Adds additional security measures. Use this in production, when serving your app over HTTPS.
cookie_name – The name of the cookie used to store the session token. Only override this if the name of the cookie clashes with other cookies.
template_path – If you want to override the default login HTML template, you can do so by specifying the absolute path to a custom template. For example '/some_directory/login.html'. Refer to the default template at piccolo_api/templates/session_login.html as a basis for your custom template.
hooks – Allows you to run custom logic at various points in the login process. See LoginHooks.
captcha – Integrate a CAPTCHA service, to provide protection against bots. See Captcha.
styles – Modify the appearance of the HTML template using CSS.

session_logout¶

This unsets the cookie value, and invalidates the session in the database, if you send a POST request.

If you send a GET request, a simple logout form is rendered, where a user can manually logout.

Hint

You can use a custom logout template, which matches the look and feel of your application. See the template_path parameter.

Examples¶

Here’s a Starlette example:

from piccolo_api.session_auth.endpoints import session_logout
from starlette import Starlette

app = Starlette()

app.mount('/logout/', session_logout())

Here’s a FastAPI example:

from piccolo_api.session_auth.endpoints import session_logout
from fastapi import FastAPI

app = FastAPI()

app.mount('/login/', session_logout())

Source¶

piccolo_api.session_auth.endpoints.session_logout(session_table: Type[SessionsBase] = SessionsBase, cookie_name: str = 'id', redirect_to: str | None = None, template_path: str | None = None, styles: Styles | None = None) → Type[SessionLogoutEndpoint][source]¶

An endpoint for clearing a user session.

Parameters:

session_table – Which table to store the session in. It defaults to SessionsBase.
cookie_name – The name of the cookie used to store the session token. Only override this if the name of the cookie clashes with other cookies.
redirect_to – Where to redirect to after logging out.
template_path – If you want to override the default logout HTML template, you can do so by specifying the absolute path to a custom template. For example '/some_directory/logout.html'. Refer to the default template at piccolo_api/templates/logout.html as a basis for your custom template.
styles – Modify the appearance of the HTML template using CSS.