Authentication

pleate_backend.accounts holds the user model (pleate_accounts.User, email as the username) and every account flow. It is mounted at /api/auth. Passwords are hashed with Argon2, must be at least 10 characters and pass Django's similarity, common and numeric validators.

Endpoints

The user

{
  "id": "6720c1f4a3b2c1d0e9f8a7b6",
  "email": "ada@plate.dev",
  "name": "Ada Lovelace",
  "display_name": "Ada Lovelace",
  "email_verified": true,
  "locale": "en",
  "timezone": "Europe/Rome",
  "preferences": { "theme": "dark" },
  "avatar_url": "/api/auth/avatars/6720c1f4a3b2c1d0e9f8a7b6?v=1a2b3c4d",
  "has_password": true,
  "is_staff": false,
  "date_joined": "2026-03-14T09:12:00Z",
  "extra": {
    "roles": ["editor"],
    "permissions": ["catalog.change_product"],
    "features": ["new-editor"],
    "mfa_enabled": true,
    "oauth_providers": ["google"],
    "subscription": { "plan_id": "pro", "status": "active", "current_period_end": "2026-11-14T09:12:00Z", "cancel_at_period_end": false }
  }
}

extra is filled by the installed apps. Add your own field from any app's ready():

from pleate_backend.accounts.me import register_me_field

register_me_field("household", lambda user: user.household_id and str(user.household_id))

On the frontend, useMe() returns the user or null (a 401 is not an error) plus hasRole, hasPermission and hasFeature helpers.

Signing up

Signup sends the verify_email email with a link to FRONTEND_PATHS["VERIFY_EMAIL"]. With REQUIRE_EMAIL_VERIFICATION off (the default) the user is signed in at once and can verify later; with it on, login answers email_not_verified until the link is opened. The page behind the link calls useVerifyEmail(token).

Leaving verification optional has a cost: anyone can sign up with an address they do not own, then attach a social login, 2FA, API keys or webhooks before the real owner shows up. When the owner resets the password of an account that was never verified, all of that is removed (API keys are revoked, social links, 2FA and webhook endpoints deleted). Turn REQUIRE_EMAIL_VERIFICATION on if unverified accounts should not be usable at all.

Passwords

The reset email links to FRONTEND_PATHS["RESET_PASSWORD"] with a token valid for PASSWORD_RESET_TIMEOUT (one hour). The token stops working once the password changes, and at most three emails per address are sent per hour. On that page:

"use client";
import { ResetPasswordForm } from "pleate/auth/reset-password-form";
import { useResetPassword } from "pleate-client/react";
import { useSearchParams } from "next/navigation";

export default function ResetPassword() {
  const token = useSearchParams().get("token");
  const reset = useResetPassword(token, { onSuccess: () => location.assign("/login") });
  if (reset.checkingToken) return null;
  if (!reset.tokenValid) return <p>This link expired. Ask for a new one.</p>;
  return <ResetPasswordForm {...reset.resetPasswordFormProps} />;
}

A successful reset or password change signs out every other session, revokes every API key and emails a security notice. A reset also marks the email as verified, since the link proves the inbox.

Login protection

Failed logins are counted in sliding windows, before the password is checked, so parallel guesses cannot slip past the limit: per account and IP address (5 in 15 minutes), per account from any address (50 in an hour) and per IP address (30 in 15 minutes). Someone guessing from one address locks only that address out of the account, not the owner. Past a limit the endpoint answers 429 too_many_attempts with retry_after, even for the right password. A successful login clears its account and IP counter and gives back its other attempts; a password reset clears the account counters. The counters fail closed: if the cache is down, logins are refused rather than left unprotected.

Sessions

Sessions use a MongoDB backed engine (pleate_backend.accounts.sessions) that keeps one row per session with the user, IP, user agent and last activity, refreshed by SessionActivityMiddleware. Ids in the API are derived from the session key, never the key itself.

Export and deletion

GET /auth/me/export answers a JSON file with the account and a section from each app (files, notifications, activity, API keys, conversations, billing...). Apps contribute through the collect_user_data signal:

from django.dispatch import receiver
from pleate_backend.accounts.signals import collect_user_data

@receiver(collect_user_data)
def export_orders(sender, user, request, **kwargs):
    return "orders", list(Order.objects.filter(user=user).values("id", "total", "created_at"))

Deleting the account requires the password (or typing the email when the account has none and DELETE_ACCOUNT_REQUIRES_PASSWORD is on), sends account_deleted, signs out every session and deletes the user. Foreign keys cascade; blobs that live outside MongoDB, such as files in S3, are removed by pre_delete handlers.

Settings

PLEATE["AUTH"], merged key by key with the defaults:

Links in emails are built from PLEATE["FRONTEND_URL"] and PLEATE["FRONTEND_PATHS"]:

Error codes

Signals

pleate_backend.accounts.signals. Audit, notifications and webhooks listen to them; so can you. All send user and request.

• user_signed_up, email_verified, password_changed, password_reset
• email_changed (also old_email), sessions_revoked (also count)
• account_deleted, sent before deletion (also email)
• collect_user_data, for the export