Endpoints

register

An endpoint for registering a user. If you send a GET request to this endpoint, a simple registration form is rendered, where a user can manually sign up.

../_images/register_template.png

Hint

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

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

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

Examples

Here’s a Starlette example:

from piccolo_api.register.endpoints import register
from starlette import Starlette

app = Starlette()

app.mount('/register/', register(redirect_to="/login/"))

Here’s a FastAPI example:

from fastapi import FastAPI
from piccolo_api.register.endpoints import register

app = FastAPI()

app.mount('/register/', register(redirect_to="/login/"))

Security

The endpoint is fairly simple, and works well for building a quick prototype, or internal application. If it’s being used on the public internet, then extra precautions are required.

Rate limiting

One option is to apply rate limiting to this endpoint. This can be done using RateLimitingMiddleware. Modifying the FastAPI example above:

from fastapi import FastAPI
from piccolo_api.rate_limiting.middleware import (
    RateLimitingMiddleware, InMemoryLimitProvider
)
from piccolo_api.register.endpoints import register

app = FastAPI()

app.mount(
    '/register/',
    RateLimitingMiddleware(
        register(redirect_to="/login/"),
        InMemoryLimitProvider(
            timespan=3600,  # 1 hour
            limit=20,
            block_duration=86400  # 24 hours
        )
    )
)

We have used quite aggressive rate limiting here - there is no reason for a user to visit a registration page a large number of times.

CAPTCHA

Alternatively, we can easily integrate a CAPTCHA service. Sign up for an account with hCaptcha or reCAPTCHA, and then do the following:

from fastapi import FastAPI
from piccolo_api.register.endpoints import register
from piccolo_api.shared.auth.captcha import hcaptcha, recaptcha_v2

app = FastAPI()

# To use hCaptcha:
app.mount(
    '/register/',
    register(
        redirect_to="/login/",
        captcha=hcaptcha(
            site_key='my-site-key',
            secret_key='my-secret-key',
        )
    )
)

# To use reCAPTCHA:
app.mount(
    '/register/',
    register(
        redirect_to="/login/",
        captcha=recaptcha_v2(
            site_key='my-site-key',
            secret_key='my-secret-key',
        )
    )
)

For a complete example app, see here.

Building your own

There is no one-size-fits-all registration solution. You can use this endpoint as a basis for your own solution, which fits the needs of your application. For example, you can add extra registration fields.

Source

piccolo_api.register.endpoints.register(auth_table: t.Type[BaseUser] = BaseUser, redirect_to: t.Union[str, URL] = '/login/', template_path: t.Optional[str] = None, user_defaults: t.Optional[t.Dict[str, t.Any]] = None, captcha: t.Optional[Captcha] = None, styles: t.Optional[Styles] = None, read_only: bool = False) t.Type[RegisterEndpoint][source]

An endpoint for register user.

Parameters:
  • auth_table – Which Table to create the user in. It defaults to BaseUser.

  • redirect_to – Where to redirect to after successful registration.

  • template_path – If you want to override the default register HTML template, you can do so by specifying the absolute path to a custom template. For example '/some_directory/register.html'. Refer to the default template at piccolo_api/templates/register.html as a basis for your custom template.

  • user_defaults

    These values are assigned to the new user. An example use case is setting active = True on each new user, so they can immediately login (not recommended for production, as it’s better to verify their email address first, but OK for a prototype app):

    register(user_defaults={'active': True})
    

  • captcha – Integrate a CAPTCHA service, to provide protection against bots. See Captcha.

  • styles – Modify the appearance of the HTML template using CSS.

Read_only:

If True, the endpoint only responds to GET requests. It’s not commonly needed, except when running demos.