Web Console Api

The web console’s React apps read and change data through the web console api, a set of JSON endpoints under /api/web/. It is the backend half of the Django-React Integration, and the console’s own backend: the list, clone, rename and delete actions of every resource list page, the dashboard’s widgets, the Prompt Passthrough’s providers, the server log stream, and the like. Every path that the console’s pages fetch is under /api/, and every other path is a page. The reasons are in ADR-034: The Web Console Api.

How it differs from the public api

/api/v1/

/api/web/

Clients

The cli, the SDKs, any program

The web console’s React apps only

Authentication

An api key, in the Authorization header

The browser’s Django session, with its CSRF token in the X-CSRFToken header

Compatibility

Semantic versioning: a breaking change needs a new major version

None: an endpoint changes with the page that calls it

Documented in

The OpenAPI document, at /docs/openapi/

This page, and each endpoint’s docstring

Shape

Resources and commands

Whatever the page needs, e.g. one dashboard widget’s rows

Both call the same models, brokers and helpers. A generic operation that other clients would want belongs in /api/v1/ too.

Layout

Each Django app mounts its endpoints at /api/web/<app label>/, from its own api/web/urls.py, beside its api/v1/urls.py. smarter.apps.api.web.urls includes them all, and smarter.apps.api.urls mounts it at web/. Each module has a reverse names class, <App>ApiWebReverseNames, whose namespace is api:web:<app> and whose names are derived from the view classes, as ADR-032 describes.

A React app never builds these urls itself. The Django view that renders its page reverses the url and passes it to the app in an attribute of its root element, as Django-React Integration describes:

from smarter.apps.guardrail.api.web.urls import GuardrailApiWebReverseNames
from smarter.lib.django.shortcuts import reverse

url = reverse(GuardrailApiWebReverseNames.namespace, GuardrailApiWebReverseNames.listview_all)
# "/api/web/guardrail/listview/"

The resource lists

Every resource list page has the same five endpoints, all POSTs, served by a SmarterListApiView and its clone, rename and delete views. The actions are siblings of listview/, so a React app derives them from its list url with actionUrl() in @smarter/common.

Path

Does

listview/, listview/<owned|shared|all>/

One page of the list. See List Pagination, Search and Sorting.

clone/<id>/<new_name>/

Copies the resource for the user.

rename/<id>/<new_name>/

Renames it.

delete/<id>/

Deletes it, unless something uses it.

List

Prefix

Reverse names

API Keys

/api/web/authtoken/

AuthTokenApiWebReverseNames

Budgets

/api/web/account/budget/ (listview/ and delete/ only)

AccountApiWebReverseNames

Connections

/api/web/connection/

ConnectionApiWebReverseNames

Custom Domains

/api/web/llmclient/custom-domains/

LLMClientApiWebReverseNames

Guardrails

/api/web/guardrail/

GuardrailApiWebReverseNames

Infrastructure resources

/api/web/infrastructure/ (listview/ only)

InfrastructureApiWebReverseNames

LLMClients (the workbench)

/api/web/prompt/

PromptApiWebReverseNames

LLMHosts

/api/web/llmhost/

LLMHostApiWebReverseNames

LLMHost Computes

/api/web/llmhost/compute/

LLMHostApiWebReverseNames

LLM Tools

/api/web/llmtool/, plus listview/extensions/

PluginApiWebReverseNames

MCPClients

/api/web/mcpclient/

MCPClientApiWebReverseNames

Orchestrators

/api/web/orchestrator/

OrchestratorApiWebReverseNames

Providers

/api/web/provider/

ProviderApiWebReverseNames

Proxies

/api/web/proxy/, when SMARTER_ENABLE_PROXY is true

ProxyApiWebReverseNames

Secrets

/api/web/secret/

SecretApiWebReverseNames

Vector Searches

/api/web/vectorsearch/

VectorsearchApiWebReverseNames

Vector Stores

/api/web/vectorstore/, when SMARTER_ENABLE_VECTORSTORE is true

VectorstoreApiWebReverseNames

Each list’s console page stays at its own path (/guardrail/, /secret/, …). Its view class is named after its list api’s, e.g. GuardrailListView for GuardrailListApiView, which is how listview_registry() pairs them.

The session

GET /api/web/session/ tells the console who is using it and how the platform is set up, in one call: the signed-in user, the account the console acts for, the platform’s branding, which ways to sign in are offered, which optional features are on, the languages, the state of the welcome dialog and the onboarding hints, and the sidebar’s links and badge counts. A visitor who isn’t signed in gets the same response with user, account, onboarding, welcome, badges and sidebar set to null, which is all that the sign-in pages need.

The sidebar’s links are the urls of the server-rendered sidebar’s (sidebar_context()). The backend decides which the user has: a link that the platform has turned off, e.g. Proxies, or that the user may not use, e.g. the Terminal and Infrastructure Resources for a superuser only and the Django admin for staff, is null. The console decides the sections, their order, the labels and the icons. It is the one GET of this api, so that the console can call it before it has a CSRF token, and it sets the CSRF cookie. It is never cached.

The single-page console (ADR-035) calls it when it starts, and again after the user signs in, signs out or changes profile. Its response is ConsoleSession, whose JSON Schema, console-session.schema.json, is generated by manage.py export_console_session_schema. A test fails if the committed copy is out of date.

Signing in

The console’s sign-in pages call the account api, under /api/web/account/. Signing in, signing out and activating an account answer with the new session, so that the console needn’t ask for it again. A refused request answers with AccountErrors: a message for the whole form, and the messages of each field, which the console shows beside it.

Path

Does

login/

Signs in with an email address and password. An unknown address and a wrong password get the same answer, so that it doesn’t reveal which addresses have accounts. The right password of an account that isn’t activated yet gets 403, and a message that says so.

logout/

Signs out. The console’s sign-out, and the user menu’s Sign Out, call it.

register/

Creates an inactive user, and emails them a link to activate their account, while the ENABLE_ACCOUNT_REGISTRATION switch is on; otherwise 404. The password must pass Django’s password validators.

activate/<uidb64>/<token>/

Activates the account of an emailed link, and signs its user in. Signing in uses the link up.

activation-resend/

Emails a new activation link, and answers the same whether or not the address has an account that is waiting to be activated.

password-reset-request/

Emails a password reset link, and answers the same whether or not the address has an account.

password-reset/<uidb64>/<token>/

GET checks an emailed link; POST sets the new password, which must pass the validators.

profile-image/

The user menu’s profile image: POST uploads the signed-in user’s own image, a multipart form; DELETE removes it. See Dashboard Authentication - Profile Image.

data-export/

The user menu’s Download My Data: GET says where the link goes and how many exports are left today; POST starts an export, or returns the one in progress. See Dashboard Authentication - Download My Data.

data-export/<id>/

GET an export’s progress, which the dialog polls.

user-profiles/

GET lists the user’s profiles, one per account, and which one the console acts as.

user-profiles/select/

POST chooses the profile that the console acts as, for the rest of the session. See User Menu React Component.

Signing in, signing up and asking for an activation or password reset link are limited to ten a minute per IP address, by SmarterCredentialsRateThrottle, on top of the api’s general rate limits. Every POST needs the CSRF token that the session api sets. Social sign-in stays a redirect flow, through /social-auth/. The emailed links keep their paths, which the console serves: /account/activate/<uidb64>/<token>/ and /password-reset-link/<uidb64>/<token>/.

A user who signs up with a password proves that the email address is theirs by following the activation link (smarter.apps.account.activation). Users that social sign-in creates are inactive too, but an administrator activates them, and they can’t ask for an activation link: see SOCIAL_AUTH_CREATE_USERS in settings/base.py. The pipeline sends them to /account/inactive/ meanwhile, which the console serves, as it does /account/already-associated/, for a social account that belongs to another user.

The other endpoints

Path

Does

/api/web/dashboard/my-resources/, service-health/, charges/, budgets/, budgets/<record locator>/series/, activity/, getting-started/, quick-actions/, search/

The dashboard’s widgets, and its global search. See Dashboard.

/api/web/dashboard/resource/<kind>/<record locator>/, resource/<record locator>/

A resource’s manifest, hierarchy and dependents, for a list row’s detail, and for the console’s manifest pages, which know only the record locator: the kind is then the resource’s own. See Resource Detail.

/api/web/dashboard/welcome/, welcome/dismiss/, onboarding/seen/

The welcome card and the onboarding tour.

/api/web/dashboard/passthrough/providers/

The Prompt Passthrough’s providers and their models, when ENABLE_DASHBOARD_PASSTHROUGH_PROMPT is true.

/api/web/dashboard/logs/stream/

The user’s server log stream, when SMARTER_ENABLE_DASHBOARD_SERVER_LOGS is true.

/api/web/dashboard/terminal/ticket/

A one-time ticket that opens the Terminal’s WebSocket.

/api/web/prompt/llm-clients/<hashed_id>/manifest/, architecture/, deployment/, deployment/api-keys/create/, attach/ and detach/

The Prompt Engineer’s Workbench’s Manifest, Architecture and Deployment tabs, and the Deployment tab’s api key actions. The workbench’s chat reads its configuration from the public api, /api/v1/llm-clients/<hashed_id>/config/, as Smarter Chat does on any page.

/api/web/llmtool/extensions/

The Extensions console: list/, registry/, check-updates/, install/, upload/ and accounts/, then each extension’s <slug>/, with its enable/, disable/, update/, rollback/, configure/, availability/ and uninstall/. Those six fixed names are reserved, so no extension’s slug can be one of them.

Not yet in the web console api

One console endpoint remains beside its page: the Terminal’s WebSocket, ws/terminal/. The workbench’s chat uses the public api, /api/v1/llm-clients/<hashed_id>/config/ and prompt/, which a deployed LLMClient’s own host serves too.

Adding an endpoint

  1. Write the view, e.g. a SmarterListApiView subclass or a SmarterAuthenticatedNeverCachedWebView that returns JSON.

  2. Route it in the app’s api/web/urls.py, named through its <App>ApiWebReverseNames class. An app that has none yet copies smarter/apps/guardrail/api/web/urls.py, and adds itself to smarter.apps.api.web.urls, behind the same feature flag as its page, if it has one.

  3. Reverse the url in the page’s view, and pass it to the React app in its root element’s attributes.

  4. Test it through the class, and assert its path once. A resource list’s tests get all five endpoints from ResourceViewsTestMixin, given web_reverse_names.

Technical Reference

The web console’s api, mounted at /api/web/.

This is the backend half of Smarter’s Django-React integration (Django-React Integration). These are the endpoints that the web console’s React apps call: the list, clone, rename and delete actions of each resource list page, the dashboard’s widgets, and the like. They are internal to the console. Unlike /api/v1/, they carry no compatibility promise, they are not in the OpenAPI document, and they authenticate with the browser’s Django session and CSRF token. See ADR-034: The Web Console Api and Web Console Api.

Constants for the web console’s api.

smarter.apps.api.web.const.namespace = 'web'

The url namespace of the web console’s api, mounted at /api/web/.

smarter.apps.api.web.const.path_namespace = 'api:web'

The web console api’s namespaces from the root urlconf, api:web.

An app’s api/web/urls.py prefixes its own namespace with it, e.g. f"{path_namespace}:{namespace}" is api:web:guardrail.

URL configuration for the web console’s api, mounted at /api/web/.

Each Django app that has a console page with a React app mounts its endpoints here, under its app label, from its own api/web/urls.py, e.g. /api/web/guardrail/listview/. The endpoints are internal to the web console: see smarter.apps.api.web.

These endpoints are part of Smarter’s Django-React integration. The Django view that renders a console page reverses their urls and passes them to the page’s React app, in the attributes of its root element, and the app calls them with the browser’s Django session and CSRF token. See Django-React Integration.

class smarter.apps.api.web.urls.ApiWebReverseNames[source]

The names of the web console api’s own urls, the ones that belong to no Django app.

console_session_view = 'console_session_view'
namespace = 'api:web'

The contract of the web console’s session api, GET /api/web/session/, as Pydantic models.

The single-page console (ADR-035) calls it when it starts, and again after the user signs in, signs out or changes profile. It replaces what Django’s context processors and the React apps’ template tags put into each server-rendered page: who the user is, the account that the console acts for, the platform’s branding, which sign-in options and features are on, the languages, the SAM kinds, and the state of the welcome dialog and onboarding hints. The JSON is camelCase.

A request without a signed-in user gets a ConsoleSession whose user, account, onboarding, welcome, badges and sidebar are null: what the sign-in pages need, and nothing about any user.

manage.py export_console_session_schema writes the models’ JSON Schema to console-session.schema.json, beside this module, from which @smarter/console generates its TypeScript types (make console-session-contract). A test fails if the committed schema is out of date.

class smarter.apps.api.web.session.contract.ConsoleAccount(**data)[source]

The account that the console acts for: that of the user’s selected profile.

model_config = {'alias_generator': <function to_camel>, 'extra': 'forbid', 'json_schema_serialization_defaults_required': True, 'serialize_by_alias': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class smarter.apps.api.web.session.contract.ConsoleBadges(**data)[source]

The counts that the sidebar shows beside its items.

model_config = {'alias_generator': <function to_camel>, 'extra': 'forbid', 'json_schema_serialization_defaults_required': True, 'serialize_by_alias': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class smarter.apps.api.web.session.contract.ConsoleBranding(**data)[source]

The platform’s identity and contacts, which the console shows in its header, footer and sign-in pages.

model_config = {'alias_generator': <function to_camel>, 'extra': 'forbid', 'json_schema_serialization_defaults_required': True, 'serialize_by_alias': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class smarter.apps.api.web.session.contract.ConsoleCookies(**data)[source]

The names and domain of Django’s cookies, which the console’s api calls send.

model_config = {'alias_generator': <function to_camel>, 'extra': 'forbid', 'json_schema_serialization_defaults_required': True, 'serialize_by_alias': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class smarter.apps.api.web.session.contract.ConsoleFlags(**data)[source]

The console’s optional features: which pages exist, and which tabs and widgets show.

model_config = {'alias_generator': <function to_camel>, 'extra': 'forbid', 'json_schema_serialization_defaults_required': True, 'serialize_by_alias': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class smarter.apps.api.web.session.contract.ConsoleLanguage(**data)[source]

The console’s languages, and the one that this response, and the session, are in.

model_config = {'alias_generator': <function to_camel>, 'extra': 'forbid', 'json_schema_serialization_defaults_required': True, 'serialize_by_alias': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class smarter.apps.api.web.session.contract.ConsoleLanguageOption(**data)[source]

A language that the console is translated into.

model_config = {'alias_generator': <function to_camel>, 'extra': 'forbid', 'json_schema_serialization_defaults_required': True, 'serialize_by_alias': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class smarter.apps.api.web.session.contract.ConsoleOnboarding(**data)[source]

The state of the console’s onboarding hints for the user.

model_config = {'alias_generator': <function to_camel>, 'extra': 'forbid', 'json_schema_serialization_defaults_required': True, 'serialize_by_alias': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class smarter.apps.api.web.session.contract.ConsoleSession(**data)[source]

Everything that the console needs to start, for the request’s user, or for a visitor who isn’t signed in.

model_config = {'alias_generator': <function to_camel>, 'extra': 'forbid', 'json_schema_serialization_defaults_required': True, 'serialize_by_alias': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class smarter.apps.api.web.session.contract.ConsoleSessionModel(**data)[source]

The base class of the contract’s models: camelCase JSON, and no fields that a model doesn’t define.

model_config = {'alias_generator': <function to_camel>, 'extra': 'forbid', 'json_schema_serialization_defaults_required': True, 'serialize_by_alias': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

to_json()[source]

The model as the view sends it.

Return type:

dict[str, Any]

class smarter.apps.api.web.session.contract.ConsoleSidebar(**data)[source]

The urls of the sidebar’s links, reversed by the backend.

A link that the platform or the user doesn’t have is null, and the sidebar leaves it out.

model_config = {'alias_generator': <function to_camel>, 'extra': 'forbid', 'json_schema_serialization_defaults_required': True, 'serialize_by_alias': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class smarter.apps.api.web.session.contract.ConsoleSignIn(**data)[source]

The ways to sign in or sign up that the sign-in pages offer.

model_config = {'alias_generator': <function to_camel>, 'extra': 'forbid', 'json_schema_serialization_defaults_required': True, 'serialize_by_alias': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class smarter.apps.api.web.session.contract.ConsoleUser(**data)[source]

The signed-in user.

model_config = {'alias_generator': <function to_camel>, 'extra': 'forbid', 'json_schema_serialization_defaults_required': True, 'serialize_by_alias': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class smarter.apps.api.web.session.contract.ConsoleWelcome(**data)[source]

The state of the welcome dialog for the user.

model_config = {'alias_generator': <function to_camel>, 'extra': 'forbid', 'json_schema_serialization_defaults_required': True, 'serialize_by_alias': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

smarter.apps.api.web.session.contract.RESPONSE_MODELS: tuple[type[BaseModel], ...] = (<class 'smarter.apps.api.web.session.contract.ConsoleSession'>,)

What the view sends.

(<class 'smarter.apps.api.web.session.contract.ConsoleSession'>, )
smarter.apps.api.web.session.contract.SCHEMA_PATH = PosixPath('/Users/mcdaniel/Desktop/gh/smarter-sh/smarter/smarter/smarter/apps/api/web/session/console-session.schema.json')

The committed JSON Schema of the contract.

smarter.apps.api.web.session.contract.contract_schema()[source]

The contract’s JSON Schema (draft 2020-12): one definition, in $defs, per model.

It also has the models of the console’s account api, smarter.apps.account.api.web.contract, so that the console generates every type it sends and receives from one schema.

Return type:

dict[str, Any]

smarter.apps.api.web.session.contract.contract_schema_json()[source]

The contract’s JSON Schema, as the text of console-session.schema.json.

Return type:

str

The web console’s session api, GET /api/web/session/.

It answers every request, signed in or not, with a ConsoleSession, and sets the CSRF cookie, so that the single-page console can make its first POST, e.g. to sign in. See smarter.apps.api.web.session.contract.

This endpoint is part of Smarter’s Django-React integration. See Django-React Integration.

class smarter.apps.api.web.session.views.ConsoleSessionView(**kwargs)[source]

GET /api/web/session/: the console’s session, for any request.

It is a GET, so that the console can call it before it has a CSRF token, and it sets the CSRF cookie. It is never cached: it describes the request’s own user.

get(request, *args, **kwargs)[source]

Return the console’s session for the request’s user.

Parameters:

request (HttpRequest) – The request.

Return type:

JsonResponse

Returns:

A ConsoleSession, as JSON.

smarter.apps.api.web.session.views.LOGO_PATH = 'images/logo/smarter-crop.png'

The logo’s path on the project’s CDN.

smarter.apps.api.web.session.views.branding()[source]

The platform’s branding, from smarter_settings.

Return type:

ConsoleBranding

Returns:

The branding that the console shows.

smarter.apps.api.web.session.views.console_account(user_profile)[source]

The account that the console acts for.

Parameters:

user_profile (UserProfile | None) – The selected profile, or None.

Return type:

ConsoleAccount | None

Returns:

The profile’s account, or None.

Raises:

ValueError – when the account has no account number.

smarter.apps.api.web.session.views.console_session(request)[source]

Everything the console needs to start, for the request’s user.

Parameters:

request (HttpRequest) – The request.

Return type:

ConsoleSession

Returns:

The session. Without a signed-in user, its user, account, onboarding, welcome, badges and sidebar are None.

smarter.apps.api.web.session.views.console_user(user, user_profile)[source]

The signed-in user, as the console shows them.

Parameters:
  • user (User) – The signed-in user.

  • user_profile (UserProfile | None) – Their selected profile, or None.

Return type:

ConsoleUser

Returns:

Who they are, their avatar, and how many accounts they belong to.

smarter.apps.api.web.session.views.cookies()[source]

The names and domain of Django’s cookies.

Return type:

ConsoleCookies

Returns:

The CSRF and session cookie names, and their domain.

smarter.apps.api.web.session.views.flags(user)[source]

The console’s optional features, for this user.

Parameters:

user (User | None) – The signed-in user, or None.

Return type:

ConsoleFlags

Returns:

Which optional pages and widgets are on. The terminal is on only for a superuser.

smarter.apps.api.web.session.views.language()[source]

The session’s language, and every language the console offers.

Return type:

ConsoleLanguage

Returns:

The language state, as LocaleMiddleware chose it for this request.

smarter.apps.api.web.session.views.sam_kinds()[source]

Every SAM kind, sorted by name, for the console’s docs pages.

Return type:

list[str]

Returns:

The kinds, e.g. ["Account", "ApiConnection", ...].

smarter.apps.api.web.session.views.selected_user_profile(user)[source]

The profile that the console acts as, chosen by smarter.apps.account.middleware.SmarterUserProfileSelectionMiddleware.

Parameters:

user (User) – The signed-in user.

Return type:

UserProfile | None

Returns:

The profile, or None for a user who has none.

smarter.apps.api.web.session.views.sidebar(user, console_flags)[source]

The sidebar’s links, for the user.

The urls are smarter.apps.dashboard.context_processors.sidebar_context()’s, which is cached. A link that the platform or the user doesn’t have is None.

Parameters:
  • user (User) – The signed-in user.

  • console_flags (ConsoleFlags) – The console’s optional features, for the user.

Return type:

ConsoleSidebar

Returns:

The links.

smarter.apps.api.web.session.views.sign_in_options()[source]

The ways to sign in or sign up that the sign-in pages offer.

Return type:

ConsoleSignIn

Returns:

Which OAuth providers, sign-up, footer links and doodle are on.

smarter.apps.api.web.session.views.welcome(request, user)[source]

The welcome dialog’s state for the user.

Parameters:
  • request (HttpRequest) – The request, whose session records whether the dialog was closed in this session.

  • user (User) – The signed-in user.

Return type:

ConsoleWelcome

Returns:

Whether the dialog shows at startup, and whether it opens by itself now.

The contract of the console’s account api, /api/web/account/: its request bodies and responses, as Pydantic models.

Signing in, signing out and activating an account answer with the new ConsoleSession, so that the console needn’t ask again. Signing up, asking for a new activation link and the password reset endpoints answer with an AccountMessage. A refused request answers with an AccountErrors: a message for the whole form, and one or more messages per field, which the console shows beside the fields. The JSON is camelCase.

The models are part of the console’s schema, console-session.schema.json: see smarter.apps.api.web.session.contract.contract_schema().

class smarter.apps.account.api.web.contract.AccountErrors(**data)[source]

A request that was refused, with why.

model_config = {'alias_generator': <function to_camel>, 'extra': 'forbid', 'json_schema_serialization_defaults_required': True, 'serialize_by_alias': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class smarter.apps.account.api.web.contract.AccountMessage(**data)[source]

A request that succeeded, with a message for the user.

model_config = {'alias_generator': <function to_camel>, 'extra': 'forbid', 'json_schema_serialization_defaults_required': True, 'serialize_by_alias': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class smarter.apps.account.api.web.contract.ActivationResendRequest(**data)[source]

The body of POST /api/web/account/activation-resend/.

model_config = {'alias_generator': <function to_camel>, 'extra': 'forbid', 'json_schema_serialization_defaults_required': True, 'serialize_by_alias': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class smarter.apps.account.api.web.contract.NewPasswordRequest(**data)[source]

The body of POST /api/web/account/password-reset/<uidb64>/<token>/.

model_config = {'alias_generator': <function to_camel>, 'extra': 'forbid', 'json_schema_serialization_defaults_required': True, 'serialize_by_alias': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class smarter.apps.account.api.web.contract.PasswordResetRequest(**data)[source]

The body of POST /api/web/account/password-reset-request/.

model_config = {'alias_generator': <function to_camel>, 'extra': 'forbid', 'json_schema_serialization_defaults_required': True, 'serialize_by_alias': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

smarter.apps.account.api.web.contract.REQUEST_MODELS = (<class 'smarter.apps.account.api.web.contract.SignInRequest'>, <class 'smarter.apps.account.api.web.contract.SignUpRequest'>, <class 'smarter.apps.account.api.web.contract.ActivationResendRequest'>, <class 'smarter.apps.account.api.web.contract.PasswordResetRequest'>, <class 'smarter.apps.account.api.web.contract.NewPasswordRequest'>)

What the console sends.

(
    <class 'smarter.apps.account.api.web.contract.SignInRequest'>,
    <class 'smarter.apps.account.api.web.contract.SignUpRequest'>,
    <class 'smarter.apps.account.api.web.contract.ActivationResendRequest'>,
    <class 'smarter.apps.account.api.web.contract.PasswordResetRequest'>,
    <class 'smarter.apps.account.api.web.contract.NewPasswordRequest'>,
)
smarter.apps.account.api.web.contract.RESPONSE_MODELS = (<class 'smarter.apps.account.api.web.contract.AccountMessage'>, <class 'smarter.apps.account.api.web.contract.AccountErrors'>)

What the views send, besides the console session.

(
    <class 'smarter.apps.account.api.web.contract.AccountMessage'>,
    <class 'smarter.apps.account.api.web.contract.AccountErrors'>,
)
class smarter.apps.account.api.web.contract.SignInRequest(**data)[source]

The body of POST /api/web/account/login/.

model_config = {'alias_generator': <function to_camel>, 'extra': 'forbid', 'json_schema_serialization_defaults_required': True, 'serialize_by_alias': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class smarter.apps.account.api.web.contract.SignUpRequest(**data)[source]

The body of POST /api/web/account/register/.

model_config = {'alias_generator': <function to_camel>, 'extra': 'forbid', 'json_schema_serialization_defaults_required': True, 'serialize_by_alias': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

The console’s account api, /api/web/account/: signing in and out, signing up and activating an account,.

and resetting a password.

These replace what the server-rendered sign-in pages’ forms did, as JSON for the single-page console (ADR-035). Every POST needs the CSRF token, which GET /api/web/session/ sets. Signing in, signing up and asking for an activation or password reset link are limited per IP address by SmarterCredentialsRateThrottle. The bodies and responses are the models of smarter.apps.account.api.web.contract.

These endpoints are part of Smarter’s Django-React integration. See Django-React Integration.

class smarter.apps.account.api.web.views.AccountApiView(**kwargs)[source]

The base class of the account api’s views: JSON bodies, and the credentials rate limit.

read_body(request, model)[source]

The request’s body, as the endpoint’s model.

Parameters:
Return type:

TypeVar(RequestModel, bound= ConsoleSessionModel)

Returns:

The body.

Raises:

InvalidRequest – when the body isn’t JSON, or isn’t the model.

throttle_credentials(request)[source]

Check the request against the credentials rate limit.

Parameters:

request (HttpRequest) – The request.

Return type:

JsonResponse | None

Returns:

A 429 response if the address has made too many attempts, otherwise None.

class smarter.apps.account.api.web.views.ActivateApiView(**kwargs)[source]

POST /api/web/account/activate/<uidb64>/<token>/: activate an account with its emailed link, and sign in.

The console serves the emailed link, /account/activate/<uidb64>/<token>/, and calls this with its two parts. It isn’t rate limited: the token is the credential, and a guess can’t be checked faster than the password reset link’s.

post(request, *args, **kwargs)[source]

Activate the link’s user, sign them in, and answer with the new session.

Parameters:
  • request (HttpRequest) – The request.

  • kwargs – uidb64 and token.

Return type:

JsonResponse

Returns:

The new session, or 404, 403 or 400 for a link that can’t be used.

class smarter.apps.account.api.web.views.ActivationResendApiView(**kwargs)[source]

POST /api/web/account/activation-resend/: email a new activation link.

post(request, *args, **kwargs)[source]

Email a new link to the address’s inactive user, if they may activate by email.

The answer is the same either way.

Parameters:

request (HttpRequest) – The request, whose body is an ActivationResendRequest.

Return type:

JsonResponse

Returns:

200 with an AccountMessage; 400 for an invalid address; 429; or 500 if the email can’t be rendered.

exception smarter.apps.account.api.web.views.InvalidRequest[source]

A request whose body isn’t the JSON that its endpoint takes.

class smarter.apps.account.api.web.views.PasswordResetApiView(**kwargs)[source]

/api/web/account/password-reset/<uidb64>/<token>/: check an emailed link, and set a new password.

The console serves the emailed link, /password-reset-link/<uidb64>/<token>/, and calls this with its two parts.

get(request, *args, **kwargs)[source]

Check that the link can be used, before the console asks for the new password.

Parameters:
  • request (HttpRequest) – The request.

  • kwargs – uidb64 and token.

Return type:

JsonResponse

Returns:

200, or 404, 403 or 400 for a link that can’t be used.

post(request, *args, **kwargs)[source]

Set the link’s user’s new password.

Parameters:
Return type:

JsonResponse

Returns:

200; 400 with the passwords’ errors; or 404, 403 or 400 for a link that can’t be used.

class smarter.apps.account.api.web.views.PasswordResetRequestApiView(**kwargs)[source]

POST /api/web/account/password-reset-request/: email a password reset link.

post(request, *args, **kwargs)[source]

Email a link to the user who has the address, if any, and answer the same either way.

Parameters:

request (HttpRequest) – The request, whose body is a PasswordResetRequest.

Return type:

JsonResponse

Returns:

200 with an AccountMessage; 400 for an invalid address; 429; or 500 if the email can’t be rendered.

class smarter.apps.account.api.web.views.SignInApiView(**kwargs)[source]

POST /api/web/account/login/: sign in with an email address and password.

post(request, *args, **kwargs)[source]

Sign in, and answer with the new session.

An unknown address and a wrong password get the same answer, so that it doesn’t reveal which addresses have accounts.

Parameters:

request (HttpRequest) – The request, whose body is a SignInRequest.

Return type:

JsonResponse

Returns:

The new session; 400 with AccountErrors; 403 for the right password of an account that isn’t activated yet; or 429.

class smarter.apps.account.api.web.views.SignOutApiView(**kwargs)[source]

POST /api/web/account/logout/: sign out.

post(request, *args, **kwargs)[source]

Sign out, and answer with the visitor’s session.

Parameters:

request (HttpRequest) – The request.

Return type:

JsonResponse

Returns:

The session of a visitor who isn’t signed in.

class smarter.apps.account.api.web.views.SignUpApiView(**kwargs)[source]

POST /api/web/account/register/: create an inactive user, and email them an activation link.

It answers 404 while the ENABLE_ACCOUNT_REGISTRATION switch is off, as the sign-up page does.

post(request, *args, **kwargs)[source]

Create the user, and email them a link to activate their account.

Parameters:

request (HttpRequest) – The request, whose body is a SignUpRequest.

Return type:

JsonResponse

Returns:

200 with an AccountMessage; 400 with the email’s and password’s errors; 404 while sign-up is switched off; 429; or 500 if the email can’t be rendered.

smarter.apps.account.api.web.views.email_errors(email)[source]

The messages of an email address that isn’t valid.

Parameters:

email (str) – The email address.

Return type:

list[str]

Returns:

Django’s messages, translated; empty when it is valid.

smarter.apps.account.api.web.views.errors_response(detail, field_errors=None, status=HTTPStatus.BAD_REQUEST)[source]

The response to a refused request.

Parameters:
  • detail (str) – Why, for the whole form.

  • field_errors (dict[str, list[str]] | None) – The messages of each refused field, by its camelCase name.

  • status (HTTPStatus) – The http status.

Return type:

JsonResponse

Returns:

An AccountErrors, as JSON.

The response to an emailed link that can’t be used.

Parameters:

error (EmailLinkError) – Why.

Return type:

JsonResponse

Returns:

404, 403 or 400, with the reason.

smarter.apps.account.api.web.views.message_response(detail)[source]

The response to a request that succeeded, with a message for the user.

Parameters:

detail (str) – What happened.

Return type:

JsonResponse

Returns:

An AccountMessage, as JSON.

smarter.apps.account.api.web.views.password_errors(password, user)[source]

The messages of a password that Django’s password validators refuse.

Parameters:
  • password (str) – The password.

  • user (User) – Its user, so that a password like their email address is refused.

Return type:

list[str]

Returns:

The validators’ messages, translated; empty when it is accepted.

smarter.apps.account.api.web.views.session_response(request)[source]

The console’s session after signing in, out or up.

Parameters:

request (HttpRequest) – The request, whose session changed.

Return type:

JsonResponse

Returns:

The new ConsoleSession, as JSON.

smarter.apps.account.api.web.views.throttled_response(wait)[source]

The response to a request over the credentials rate limit.

Parameters:

wait (int) – The seconds to wait before retrying.

Return type:

JsonResponse

Returns:

A 429 response, with a Retry-After header.

smarter.apps.account.api.web.views.unknown_error_response()[source]

The response to a request that failed on the server, e.g. an email that couldn’t be rendered.

Return type:

JsonResponse

Returns:

500, with a message for the user.

Signing in with an email address and password, and signing up, for the console’s sign-in pages and api.

The console’s account api, smarter.apps.account.api.web.views, signs users in through these functions, which record each failure in the login audit.

smarter.apps.account.sign_in.awaits_activation(email, password)[source]

Whether this email address and password are those of a user who hasn’t activated their account yet.

Only someone who knows the password is told, so the answer doesn’t reveal which addresses have accounts.

Parameters:
  • email (str) – The email address.

  • password (str) – The password.

Return type:

bool

Returns:

True for an inactive user who may activate by email, and whose password this is.

smarter.apps.account.sign_in.email_is_taken(email)[source]

Whether another user already has this email address, in any case.

Parameters:

email (str) – The email address.

Return type:

bool

Returns:

True when a user has it.

smarter.apps.account.sign_in.sign_in_with_email(request, email, password)[source]

Sign in the user who has this email address and password, in the request’s session.

A failure is recorded in the login audit, with its reason: an unknown address, or the password failure of smarter.apps.account.login_audit.password_failure(). The caller answers every failure alike, so that the response doesn’t reveal which addresses have accounts.

Parameters:
  • request (HttpRequest) – The request, whose session the user is signed in to.

  • email (str) – The email address. An email address belongs to one user.

  • password (str) – The password.

Return type:

User | None

Returns:

The signed-in user, or None.

smarter.apps.account.sign_in.sign_up(request, email, password)[source]

Create an inactive user whose username and email address are email, and email them an activation link.

The user can sign in once they follow the link, which proves that the address is theirs. See smarter.apps.account.activation. The caller checks first that the address is free and that the password is acceptable.

Parameters:
  • request (HttpRequest) – The request, for the link’s host and the email’s template context.

  • email (str) – The email address, which is also the username.

  • password (str) – The password.

Return type:

User

Returns:

The new, inactive user.

Raises:

RuntimeError – when the email’s template can’t be rendered.

Account activation: a user who signs up with an email address and a password is inactive until they follow the.

link that the platform emails them, which proves that the address is theirs.

The link is /account/activate/<uidb64>/<token>/: see smarter.apps.account.email_links. The console serves its page, which activates the user and signs them in through the account api, smarter.apps.account.api.web.views. Signing in uses the link, so it can’t be used twice.

Users that social sign-in creates are inactive too, but are activated by an administrator, never by email: self-service activation is only for those who signed up with a password, while the ENABLE_ACCOUNT_REGISTRATION switch allowed it. See SOCIAL_AUTH_CREATE_USERS in settings/base.py.

The url name of the link, which smarter.apps.account.urls serves at /account/activate/<uidb64>/<token>/.

smarter.apps.account.activation.EMAIL_TEMPLATE_PATH = 'account/authentication/email/account-activation.html'

The email’s template.

smarter.apps.account.activation.PASSWORD_BACKEND = 'django.contrib.auth.backends.ModelBackend'

The authentication backend of a user who signed up with a password, which the activation signs them in with.

smarter.apps.account.activation.activate(request, uidb64, token)[source]

Activate the user of an emailed link, and sign them in.

Signing in changes the user’s last sign-in, which the link’s token hashes, so the link can’t be used again.

Parameters:
  • request (HttpRequest) – The request, whose session the user is signed in to.

  • uidb64 (str) – The link’s encoded user id.

  • token (str) – The link’s token.

Return type:

User

Returns:

The active, signed-in user.

Raises:

EmailLinkError – when the link is unknown, malformed, used or expired.

The absolute url of a new activation link for the user.

Parameters:
  • request (HttpRequest) – The request, for the link’s host and protocol.

  • user (User) – The user.

Return type:

str

Returns:

The link.

smarter.apps.account.activation.can_activate_by_email(user)[source]

Whether a user may activate their own account with an emailed link.

Parameters:

user (User) – The user.

Return type:

bool

Returns:

True for an inactive user who signed up with a password. A user that social sign-in created has no usable password, and waits for an administrator.

smarter.apps.account.activation.resend_activation_email(request, email)[source]

Email a new activation link to the user who has this address, if they may activate by email.

The caller answers the same either way, so that the response doesn’t reveal which addresses have accounts.

Parameters:
  • request (HttpRequest) – The request.

  • email (str) – The email address.

Return type:

bool

Returns:

True if an email was sent.

Raises:

RuntimeError – when the email’s template can’t be rendered.

smarter.apps.account.activation.send_activation_email(request, user)[source]

Email the user a link to activate their account.

Parameters:
  • request (HttpRequest) – The request, for the link’s host and the email’s template context.

  • user (User) – The inactive user.

Raises:

RuntimeError – when the email’s template can’t be rendered.

Return type:

None

Password reset links: making one, emailing it, and reading it back.

A link is /password-reset-link/<uidb64>/<token>/, which expires: see smarter.apps.account.email_links. The console serves the link’s page, and its account api, smarter.apps.account.api.web.views, uses these functions. Emails that were sent before the console served it keep working: the link’s path is the same.

smarter.apps.account.password_reset.EMAIL_TEMPLATE_PATH = 'account/authentication/email/password-reset.html'

The email’s template.

The url name of the link, which smarter.urls.console serves at /password-reset-link/<uidb64>/<token>/.

The absolute url of a new password reset link for the user.

Parameters:
  • request (HttpRequest) – The request, for the link’s host and protocol.

  • user (User) – The user.

Return type:

str

Returns:

The link.

Raises:

SmarterValueError – when user is not a User.

smarter.apps.account.password_reset.send_password_reset_email(request, email)[source]

Email a password reset link to the user who has this address, if there is one.

The caller answers the same either way, so that the response doesn’t reveal which addresses have accounts.

Parameters:
  • request (HttpRequest) – The request, for the link’s host and the email’s template context.

  • email (str) – The email address.

Return type:

bool

Returns:

True if an email was sent, False if no user has the address.

Raises:

RuntimeError – when the email’s template can’t be rendered.

The user of a password reset link, if the link is valid and hasn’t expired.

Parameters:
  • uidb64 (str) – The link’s encoded user id.

  • token (str) – The link’s token.

Return type:

User

Returns:

The user.

Raises:

EmailLinkError – when the link is unknown, malformed or expired.

A link is /<path>/<uidb64>/<token>/: the user’s encoded id and a token that expires, made by ExpiringTokenGenerator. The token hashes the user’s password and last sign-in, so a link stops working once its user changes their password or signs in. Password reset links (smarter.apps.account.password_reset) and account activation links (smarter.apps.account.activation) are both made and read here.

exception smarter.apps.account.email_links.EmailLinkError(message, status)[source]

An emailed link that can’t be used.

Parameters:
  • message (str) – Why, for the user.

  • status (HTTPStatus) – The http status that answers it: 404 for an unknown user, 403 for an expired link, 400 for a malformed or used one.

__init__(message, status)[source]

The absolute url of a new link for the user.

Parameters:
  • request (HttpRequest) – The request, for the link’s host and protocol.

  • user (User) – The user.

  • url_name (str) – The name of the link’s url, whose kwargs are uidb64 and token.

Return type:

str

Returns:

The link.

Raises:

SmarterValueError – when user is not a User.

smarter.apps.account.email_links.render_email(request, template_path, context)[source]

An email’s html, rendered from its template, without comments and minified.

Parameters:
  • request (HttpRequest) – The request, for the template’s context processors, e.g. the branding.

  • template_path (str) – The email’s template.

  • context (dict[str, dict[str, str]]) – The template’s context, e.g. the link.

Return type:

str

Returns:

The html.

Raises:

RuntimeError – when the template can’t be rendered.

The user of an emailed link, if the link is valid and hasn’t expired.

Parameters:
  • uidb64 (str) – The link’s encoded user id.

  • token (str) – The link’s token.

Return type:

User

Returns:

The user.

Raises:

EmailLinkError – when the link is unknown, malformed, used or expired.